NAV Navbar
cURL

Giới thiệu chung

Về MoMo API

MoMo Payment Platform 

  _          _ _                                     _
 | |__   ___| | | ___      __      _____  _ __| | __| |
 | '_ \ / _ \ | |/ _ \     \ \ /\ / / _ \| '__| |/ _` |
 | | | |  __/ | | (_) |     \ V  V / (_) | |  | | (_| |
 |_| |_|\___|_|_|\___/       \_/\_/ \___/|_|  |_|\__,_|

MoMo Payment Platform API là giải pháp thanh toán cho các đơn vị kinh doanh, cho phép khách hàng sử dụng tài khoản Ví MoMo để thanh toán các dịch vụ trên nhiều nền tảng khác nhau: Desktop Website, Mobile Website, Mobile Application, POS, Pay In Bill, In App MoMo

Quy trình tích hợp

Các bước cơ bản để tích hợp với MoMo:

Các hình thức tích hợp thanh toán:

Thuật ngữ

1. Tài khoản doanh nghiệp

Mỗi đối tác khi liên kết với MoMo sẽ tạo một tài khoản doanh nghiệp (M4B) để liên kết. Tài khoản này sẽ dùng để quản lý các giao dịch, lấy thông tin tích hợp (partnerCode, accessKey, publicKey,...)

2. Partner Code

Sau khi đăng ký tài khoản doanh nghiệp, mỗi đối tác sẽ được cung cấp một mã định danh duy nhất, gọi là partner code. Sử dụng mã này cùng các thông tin đi kèm để tiến hành quá trình tích hợp.

3. Mã giao dịch MoMo

Mã giao dịch MoMo (TID/transId) là mã định danh cho một giao dịch của đối tác khi thanh toán qua MoMo. TID/transId này là duy nhất trên hệ thống MoMo.

4. Mã giao dịch đối tác

Mã giao dịch đối tác (refId/orderId) là mã duy nhất mà đối tác gửi qua MoMo để yêu cầu thanh toán. Một TID sẽ ứng với một refId.

5. Access Key

Key duy nhất được cung cấp bởi MoMo. Cấp quyền truy cập vào hệ thống MoMo.

6. Secret key

Key định danh ứng với mỗi đối tác. Dùng để tạo chữ ký điện tử signature.

7. Signature

Chữ ký được tạo ra từ một thuật toán cho trước, sử dụng để kiểm tra tính đúng đắn của data truyền qua giữa 2 hệ thống. Một số thuật toán đang sử dụng là MD5, SHA1, SHA256 và Hmac. Tham khảo thêm: Wikipedia Hmac

Trong tài liệu này MoMo sử dụng thuật toán HMAC256 để tạo signature. Dữ liệu đầu vào bao gồm secretKey và data, data được tạo ra theo định dạng key1=value1&key2=value2.... Xem chi tiết hơn trong từng Request/Response

Ví dụ tạo RSA

##Dữ liệu trước khi RSA
{
  "partnerCode": "MOMOIQA420180417",
  "partnerRefId": "Merchant123556666",
  "partnerTransId": "8374736463",
  "amount": 40000,
  "description": "Thanh toan momo"
}

##Dữ liệu sau khi RSA
A7WFmmnpn6TRX42Akh/iC5DdU5hhBT9LR5QSG6rJAl70hfEkkGUx2pTCai8s+M9KMVUcJ7m52iv74yhmeEjjN10TtEJoqITBIYBG2bqcTprhDijyhV4ePU7ytDNuLxzzIvGfTYyvbsEJ2jZTSf556yod12vhYqOJSFL/U2hVuxjUahf5Rnu5R/OLalg8QmlU6nQooEuNdzEXPMd6j9EaxOCiB2oM5/9QiTN0tCNSTIVvPtnlHu5mIbBHChcwfToIL4IAiD1nbrlDuBX//CZcrZj6hFqjvU31yb/DuG02c3aqWxbZKZ8csOwF9bL30m/yGr/0BQUWgunpDPrmCosf9A==

8. Mã hóa RSA

Mã hóa RSA là một thuật toán mật mã hóa khóa công khai để bảo vệ thông tin trên đường truyền. Sử dụng một cặp key (public key và private key) để mã hóa và giải mã dữ liệu. Đối tác dùng public key do MoMo cung cấp để mã hóa data theo định dạng của MoMo, MoMo sẽ giải mã bằng private key.
Tham khảo một số cách tạo RSA của MoMo ở đây

Thông tin tích hợp

Cấu hình HTTP Request

Key Value
Content-Type application/json
Method POST
Domain Production: https://payment.momo.vn
Sandbox: https://test-payment.momo.vn

Địa chỉ IP (Internet Protocol)

Môi trường Incoming Outcoming
Sandbox 210.245.113.71 118.69.210.244
Production 118.69.212.158 118.69.210.244

Cổng thanh toán MoMo

Giới thiệu

Tham khảo hướng dẫn sau để áp dụng MoMo vào trang mua hàng của bạn

API ENDPOINT

/gw_payment/transactionProcessor

requestType: Định danh loại request

Sơ đồ xử lý

Thanh toán đơn hàng trên website desktop/mobile

Thanh toán trên Smart Tivi

Phương thức thanh toán

Request mẫu

{
  "accessKey": "F8BBA842ECF85",
  "partnerCode": "MOMO",
  "requestType": "captureMoMoWallet",
  "notifyUrl": "https://momo.vn",
  "returnUrl": "https://momo.vn",
  "orderId": "MM1540456472575",
  "amount": "150000",
  "orderInfo": "SDK team.",
  "requestId": "MM1540456472575",
  "extraData": "email=abc@gmail.com",
  "signature": "996ed81d68a1b05c99516835e404b2d0146d9b12fbcecbf80c7e51df51cac85e"
}


Sử dụng API captureMoMoWallet để yêu cầu thanh toán bằng Ví MoMo

HTTP Request

Attribute Type Required Description
partnerCode String √ Thông tin tích hợp
accessKey String √ Thông tin tích hợp
requestId String √ Định danh mỗi yêu cầu
amount String √ Số tiền cần thanh toán
Min: 1.000 VND
Max: 20.000.000 VND
Tiền tệ: VND
Kiểu dữ liệu: long
orderId String √ Mã đơn hàng của đối tác
orderInfo String √ Thông tin đơn hàng
returnUrl String √ Một URL của đối tác. URL này được sử dụng để chuyển trang (redirect) từ MoMo về trang mua hàng của đối tác sau khi khách hàng thanh toán.
Hỗ trợ: AppLink và WebLink
notifyUrl String √ API của đối tác. Được MoMo sử dụng để gửi kết quả thanh toán theo phương thức IPN (server-to-server)
requestType String √ captureMoMoWallet
signature String √ partnerCode=$partnerCode&accessKey=$accessKey
&requestId=$requestId&amount=$amount&orderId=$orderId
&orderInfo=$orderInfo&returnUrl=$returnUrl&notifyUrl=$notifyUrl
&extraData=$extraData
extraData String √ Thông tin bổ sung theo định dạng: <key>=<value>;<key>=<value>.
Giá trị mặc định là trống ""

Thông tin redirecting (returnUrl)

WebLink: Liên kết để mở website dạng: http(s)://example.com/

AppLink: Liên kết để mở mobile application.

Tìm hiểu thêm về AppLink

Phương thức thanh toán

{
  "requestId": "MM1540456472575",
  "errorCode": 0,
  "orderId": "MM1540456472575",
  "message": "Success",
  "localMessage": "Thành công",
  "requestType": "captureMoMoWallet",
  "payUrl": "https://test-payment.momo.vn/gw_payment/payment/qr?partnerCode=MOMO&accessKey=F8BBA842ECF85&requestId=MM1540456472575&amount=150000&orderId=MM1540456472575&signature=df2a347519abb91e9c1bd1bee80e675f4108cb6dbcac531979e805857293d486&requestType=captureMoMoWallet",
  "signature": "ee6a01b85ffc48a2b5d3df473da88c75cc5e879d1543d9e76ced279c10bcd646",
  "qrCodeUrl": "https://test-payment.momo.vn/gw_payment/s/zoVKZd",
  "deeplink": "momo://?action=payWithAppToken&amount=150000&fee=0&requestType=payment&orderLabel=M%C3%A3+%C4%91%C6%A1n+h%C3%A0ng&orderId=MM1540456472575&requestId=MM1540456472575&merchantnamelabel=Nh%C3%A0+cung+c%E1%BA%A5p&description=SDK+team.&partnerCode=MOMO&merchantcode=MOMO&language=vi&merchantname=MoMo+Payment&packageId=&extras=&extraData=email=abc@gmail.com&deeplinkCallback=https%3A%2F%2Ftest-payment.momo.vn%2Fgw_payment%2Fm2%3Fid%3DM7EWVy&callbackUrl=https%3A%2F%2Ftest-payment.momo.vn%2Fgw_payment%2Fm2%3Fid%3DM7EWVy&urlSubmitToken=https%3A%2F%2Ftest-payment.momo.vn%2Fgw_payment%2Fpayment_with_app%3FpartnerCode%3DMOMO%26accessKey%3DF8BBA842ECF85%26requestId%3DMM1540456472575%26orderId%3DMM1540456472575%26orderInfo%3DSDK%2Bteam.%26amount%3D150000%26signature%3Ddf2a347519abb91e9c1bd1bee80e675f4108cb6dbcac531979e805857293d486%26requestType%3DcaptureMoMoWallet%26payType%3Dapp-in-app&appScheme=",
  "deeplinkWebInApp": "http://momo//?type=webinapp&action=payment&requestId=MM1540456472575&billId=MM1540456472575&partnerCode=MOMO&partnerName=MoMo Payment&amount=150000&description=SDK team.¬ifyUrl=https://momo.vn&returnUrl=https://momo.vn&code=momo&extraData=eyJzaWduYXR1cmUiOiI0OWUzMTZhNTVkN2UxM2Q0ZjEwNGFjZjM2YTM5MzllZjg0NDk3NWU2OTJiMWU1OGM3MDFjYWUyM2ZiM2QxNDY5In0=&signature=49e316a55d7e13d4f104acf36a3939ef844975e692b1e58c701cae23fb3d1469"
}


HTTP Response

Danh sách những phương thức thanh toán mà MoMo cung cấp cho đơn vị kinh doanh

Attribute Type Required Description
requestId String √ Giống với yêu cầu ban đầu
errorCode int √ Mã lỗi
message String √ Mô tả lỗi tiếng Anh
localMessage String √ Mô tả lỗi Tiếng Việt
requestType String √ captureMoMoWallet
payUrl String √ Tham khảo cách sử dụng ở phía dưới
qrCodeUrl String Tham khảo cách sử dụng ở phía dưới
deeplink String Tham khảo cách sử dụng ở phía dưới
deeplinkWebInApp String Tham khảo cách sử dụng ở phía dưới
signature String √ requestId=$requestId&orderId=$orderId&message=$message
&localMessage=$localMessage&payUrl=$payUrl
&errorCode =$errorCode&requestType=$requestType

Cách sử dụng các phương thức thanh toán

Xử lý kết quả thanh toán

Sau khi khách hàng xác nhận thanh toán, chúng tôi sẽ thông báo kết quả thanh toán cho bạn thông qua 2 cách:

1. Giao diện

Khách hàng sẽ được chuyển (redirect) từ trang thanh toán của MoMo về trang mua hàng của đối tác dựa vào field returnUrl mà bạn đã truyền vào ở lệnh captureMoMoWallet và sẽ đính kèm thêm các tham số vào url có định dạng như sau:

returnUrl?{your_parameters}&partnerCode=partnerCode&accessKey=accessKey&requestId=requestId&amount=amount&orderId=orderId&orderInfo=orderInfo&orderType=momo_wallet&transId=transId&message=message&localMessage=localMessage&responseTime=responseTime&errorCode=errorCode&payType=payType&extraData=extraData&signature=signature

2. Server (IPN - Instant Payment Notification)

MoMo Server sẽ sử dụng API được khai báo ở field notifyUrl để gửi một HTTP Request với cấu hình bên dưới tới máy chủ đối tác.

Attribute Value Description
URL notifyUrl Đường dẫn URL
Method POST Phương thức HTTP Request
Headers content-type: application/x-www-form-urlencoded HTTP Headers
Payload Tham khảo bảng mô tả tham số bên dưới Nội dung body của HTTP

IPN REQUEST EXAMPLE

curl -X POST \
  https://example.com/momo_ipn \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'partnerCode=MOMOTUEN20190312&accessKey=ZjF6taKUohp7iN8l&requestId=1555383430&orderId=1555383430&orderInfo=&orderType=momo_wallet&transId=2302586804&errorCode=0&message=Success&localMessage=Th%C3%A0nh%20c%C3%B4ng&payType=qr&responseTime=2019-04-09%2014%3A53%3A38&extraData=&signature=e1da7982cdbc732c172e4f2909d6f70c5e2a5d2dde7e8c02dce866c6b35c9461&amount=300000'

Thông tin tham số

Bảng mô tả các tham số được MoMo đính kèm trong trong URL returnUrl và nội dung body của notifyUrl.

Attribute Type Required Description
partnerCode String √ Thông tin tích hợp
accessKey String √ Thông tin tích hợp
requestId String √ Định danh mỗi request
amount String √ Số tiền thanh toán
orderId String √ Mã đơn hàng của đối tác
orderInfo String √ Thông tin đơn hàng
orderType String √ momo_wallet
transId String √ Mã giao dịch của MoMo
errorCode int √ Trạng thái thanh toán của đơn hàng
message String √ Mô tả lỗi bằng tiếng Anh
localMessage String √ Mô tả lỗi bằng tiếng Việt
payType String √ Hình thức thanh toán: web or qr
responseTime String √ Thời gian trả kết quả thanh toán về đối tác
Định dạng: YYYY-MM-DD HH:mm:ss
Múi giờ: GMT +7
extraData String Thông tin thêm
signature String √ partnerCode=$partnerCode&accessKey=$accessKey
&requestId=$requestId
&amount=$amount&orderId=$orderId
&orderInfo=$orderInfo
&orderType=$orderType&transId=$transId
&message=$message&localMessage=$localMessage
&responseTime=$responseTime
&errorCode=$errorCode
&payType=$payType&extraData=$extraData

HTTP Response (IPN)

Kết quả phản hồi của đối tác cho MoMo sau khi MoMo gửi HTTP tới địa chỉ notifyUrl.

Key Value Description
HTTP Header Content-Type: application/json;charset=UTF-8
HTTP Status Code 200


HTTP Payload: Body của Response

Parameter Type Required Description
partnerCode String √ Thông tin tích hợp
accessKey String √ Thông tin tích hợp
requestId String √ Định danh mỗi request
orderId String √ Mã đơn hàng của đối tác
errorCode int √ Trạng thái xử lý giao dịch của đối tác
message String √ Mô tả trạng thái giao dịch của đối tác
responseTime String √ Thời gian phản hồi
Định dạng: YYYY-MM-DD HH:mm:ss
Múi giờ: GMT +7
extraData Json √ Thông tin thêm
signature String √ partnerCode=$partnerCode&accessKey=$accessKey&requestId=$requestId
&orderId=$orderId&errorCode=$errorCode&message=$message
&responseTime=responseTime&extraData=extraData

Đối với trường errorCode và message đối tác chủ động xử lý, có thể tham khảo mã lỗi của MoMo để trả về. MoMo sẽ sử dụng những thông tin này để feedback cho khách hàng nếu có lỗi xảy ra trong quá trình thanh toán từ phía đối tác.

Trạng thái giao dịch

Sử dụng field errorCode để xác định trạng thái giao dịch:

Tham khảo bảng mã lỗi để xác định chi tiết lỗi giao dịch

Kiểm tra toàn vẹn dữ liệu

Để kiểm tra thông tin tính toàn vẹn dữ liệu của giao dịch vui lòng kiểm tra signature của MoMo và signature của bạn tạo ra, nếu 2 chuỗi giống có nghĩa là hợp lệ

Lưu ý - QUAN TRỌNG

  1. Kiểm tra signature và trạng thái đơn hàng trước khi cập nhập trạng thái giao dịch
  2. Sử dụng API transactionStatus của MoMo để kiểm tra trạng thái giao dịch trước khi cập nhập.
  3. Luôn xử lý API notifyUrl để xử lý kết quả. Khắc phục trường hợp thanh toán với lỗi trình duyệt bị đóng hoặc không thể chuyển trang từ MoMo về đối tác

Kiểm tra trạng thái giao dịch

Example request

curl -X POST \
  https://test-payment.momo.vn/gw_payment/transactionProcessor \
  -H 'content-type: application/json' \
  -d '{
    "partnerCode": "123456",
    "accessKey": "F8BBA842ECF85",
    "requestId": "1527246504579",
    "orderId": "1527246478428",
    "requestType": "transactionStatus",
    "signature": "13be80957a5ee32107198920fa26aa85a4ca238a29f46e292e8c33dd9186142a"
}'

Tra cứu thông tin giao dịch

HTTP Request

Attribute Type Required Description
partnerCode String √ Thông tin tích hợp
accessKey String √ Thông tin tích hợp
requestId String √ Định danh mỗi request
orderId String √ Mã đơn hàng cần kiểm tra trạng thái
requestType String √ transactionStatus
signature String √ partnerCode=$partnerCode&accessKey=$accessKey</br>&requestId=$requestId
&orderId=$orderId&requestType=$requestType

Example response

{
    "partnerCode": "123456",
    "accessKey": "F8BBA842ECF85",
    "requestId": "1527246504579",
    "orderId": "1527246478428",
    "requestType": "transactionStatus",
    "extraData": "",
    "amount": "55000",
    "transId": "0",
    "payType": "",
    "errorCode": -1,
    "message": "Transaction init",
    "localMessage": "Giao dịch khởi tạo",
    "signature": "d4affc86b0894aa5e6ec48c43144b9c86bf770fe2e9fcc3cfb5e27871135806f"
}


HTTP Response

Attribute Type Required Description
partnerCode String √ Thông tin tích hợp
accessKey String √ Thông tin tích hợp
requestId String √ Định danh mỗi request
orderId String √ Mã đơn hàng
requestType String √ transactionStatus
amount String √ Số tiền của đơn hàng
transId String √ Mã giao dịch của MoMo
payType String √ Hình thức thanh toán. web hoặc qr. Mặc định là "" nếu không thanh toán
errorCode int √ Mã lỗi giao dịch
message String √ Mô tả lỗi Tiếng Anh
localMessage String √ Mô tả lỗi Tiếng Việt
extraData String √ Thông tin thêm. Mặc định là giá trị mà đơn vị kinh doanh truyền qua ở lệnh captureMoMoWallet
signature String √ partnerCode=$partnerCode&accessKey=$accessKey</br>&requestId=$requestId
&orderId=$orderId</br>&errorCode=$errorCode&transId=$transId
&amount=$amount&message=$message&localMessage=$localMessage
&requestType=$requestType&payType=$payType&extraData=$extraData

Hoàn tiền giao dịch

Sử dụng để hoàn tiền cho giao dịch thanh toán trước đó

Example request

{
  "partnerCode": "MOMO",
  "accessKey": "F8BBA842ECF85",
  "requestId": "1527314064527",
  "amount": "55000",
  "orderId": "1527297954700",
  "transId": "144492817",
  "requestType": "refundMoMoWallet",
  "signature": "8cdba11a7ff4cc7267d2b23c1f5d228a2ee52af1095420f9571c2d64ec6735fe"
}

HTTP Request

Attribute Type Required Description
partnerCode String √ Thông tin tích hợp
accessKey String √ Thông tin tích hợp
requestId String √ Định danh mỗi request
amount String √ Số tiền cần được hoàn tiền
orderId String √ Mã giao dịch của đối tác
transId String √ Mã giao dịch của MoMo. Mã này được MoMo cung cấp sau khi giao dịch thanh toán
thành công
requestType String √ refundMoMoWallet
signature String √ partnerCode=$partnerCode&accessKey=$accessKey&requestId=$requestId
&amount=$amount&orderId=$orderId&transId=$transId&requestType=$requestType

Example response

{
  "partnerCode": "MOMO",
  "accessKey": "F8BBA842ECF85",
  "requestId": "1527314064527",
  "amount": "55000",
  "orderId": "1527297954700",
  "transId": "144518121",
  "requestType": "refundMoMoWallet",
  "signature": "b9a823d1645fa40aa7eb924ed13dc32958257d761f5c90ea30a58ea7b2f1ee5e",
  "errorCode": 0,
  "message": "Success",
  "localMessage": "Thành công"
}

HTTP Response

Attribute Type Required Description
partnerCode String √ Thông tin tích hợp
accessKey String √ Thông tin tích hợp
requestId String √ Định danh mỗi request
amount String √ Số tiền được hoàn
requestType String √ refundMoMoWallet
transId String √ Mã giao dịch của MoMo
errorCode int √ Mã lỗi giao dịch
message String √ Mô tả lỗi Tiếng Anh
localMessage String √ Mã lỗi tiếng Việt
signature String √ partnerCode=$partnerCode&accessKey=$accessKey&requestId=$requestId
&orderId=$orderId&errorCode=$errorCode</br>&transId=$transId
&message=$message&localMessage=$localMessage&requestType=$requestType

Kiểm tra trạng thái hoàn tiền

Liệt kê tất cả danh sách giao dịch hoàn tiền của đơn hàng đã thanh toán

Example request

{
  "partnerCode": "MOMO",
  "accessKey": "F8BBA842ECF85",
  "requestId": "1540450655430",
  "orderId": "1540374459248",
  "requestType": "refundStatus",
  "signature": "fc63b6fafbbebf05d8bb76c140e9fc9df67438b01a10ce550d416624efd4ed83"
}

HTTP Request

Attribute Type Required Description
partnerCode String √ Thông tin tích hợp
accessKey String √ Thông tin tích hợp
requestId String √ Định danh mỗi request
orderId String √ Mã đơn hàng đã thanh toán
requestType String √ refundStatus
signature String √ partnerCode=$partnerCode&accessKey=$accessKey&requestId=$requestId
&orderId=$orderId&requestType=$requestType

Example response

[
  {
    "partnerCode": "MOMO",
    "accessKey": "F8BBA842ECF85",
    "requestId": "1540450655430",
    "orderId": "1540374560708",
    "amount": "55000",
    "errorCode": 0,
    "transId": "1344317",
    "requestType": "refundStatus",
    "message": "Success",
    "localMessage": "Thành công",
    "signature": "047d62d3a5a4a398dbbda065c9bcef314cf20541b4a16bc10b4a337b3abd5097"
  }
]


Response

Danh sách các giao dịch hoàn tiền

Attribute Type Required Description
partnerCode String √ Thông tin tích hợp
accessKey int √ Thông tin tích hợp
requestId String √ Định danh mỗi request
orderId String √ Mã đơn hàng hoàn tiền
amount String √ Số tiền được hoàn
requestType String √ refundStatus
transId String √ Mã giao dịch của MoMo
errorCode int √ Mã lỗi giao dịch
message String √ Mô tả lỗi Tiếng Anh
localMessage String √ Mã lỗi tiếng Việt
signature String √ partnerCode=$partnerCode&accessKey=$accessKey&requestId=$requestId
&orderId=$orderId&errorCode=$errorCode&transId=$transId
&amount=$amount&message=$message&localMessage=$localMessage
&requestType=$requestType

Bảng mã lỗi

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 lỗi gọi API

Error code Message Local mesage
0 Success Thành công
-1 Transaction init Giao dịch khởi tạo (trạng thái mặc định)
1 Empty accessKey or partnerCode Thiếu thông tin đối tác
2 OrderId is wrong format OrderId sai định dạng
4 Amount is invalid should be between 1,000VND and 20,000,000 VND Số tiền thanh toán không hợp lệ
5 Signature is wrong. Check raw signature before signed Sai thông tin chữ ký
6 OrderId exists Đơn hàng đã tồn tại
7 Pending transaction Giao dịch đang chờ xử lý
12 Duplicate request ID Vui lòng tạo requestId mới
14 Partner is not actived Đối tác chưa được kích hoạt
29 System maintenance. Please try in few minutes Hệ thống đang bảo trì
32 Transaction was purchased Giao dịch đã được thanh toán
33 Transaction can not be refunded Giao dịch không thể refund.
34 Transaction refuned Giao dịch hoàn tiền đã được xử lý
36 Expired transaction Giao dịch đã hết hạn
37 Capset exceeded Tài khoản hết hạn mức giao dịch trong ngày
38 Insufficient funds Tài khoản khách hàng không đủ tiền
44 Service not support your request Dịch vụ không hỗ trợ yêu cầu của bạn
49 Order canceled by user Giao dịch bị hủy
58 Transaction not exist Giao dịch không tồn tại
59 Error parsing body to Json object Yêu cầu không hợp lệ
63 Pay by bank source is failure Thanh toán bằng nguồn ngân hàng không thành công
80 User failed authentication Khách hàng đăng nhập thất bại
99 Error undefined Lỗi không xác định
9043 (*) User does not link bank account Khách hàng chưa liên kết tài khoản ngân hàng

Ghi chú (*):

Mã lỗi 9043: Kể từ 1/1/2019, theo quy định của Ngân hàng Nhà nước, để thực hiện giao dịch trên Ví điện tử, người dùng Ví cần thêm thông tin ngân hàng, thẻ ATM nội địa, hoặc thẻ ghi nợ Visa, Mastercard hoặc JCB.

Code mẫu

Tham khảo code mẫu

Java | PHP | NodeJs | C# | Ruby | Python

Tham khảo

Sử dụng trang bên dưới để hình dung cách MoMoPay hoạt động

Demo MoMo Payment

Các đối tác của MoMo đang sử dụng:

F.A.Q

Phương thức thanh toán

Nền tảng Mô tả hình thức thanh toán
Desktop Web 1. Khách hàng mua hàng trên website đối tác.
2. Chọn MoMo là phương thức thanh toán
3. Khách hàng được chuyển qua trang thanh toán của MoMo.
4. Khách hàng thực hiện thanh toán: Sử dụng ứng dụng MoMo để quét mã QR hoặc đăng nhập tài khoản.
5. Sau khi thanh toán khách hàng được chuyển về trang mua hàng.
Mobile Web 1. Khách hàng mua hàng trên website đối tác.
2. Chọn MoMo là phương thức thanh toán
3. Khách hàng được chuyển qua trang thanh toán của MoMo.
4. Khách hàng thực hiện thanh toán: Mở ứng MoMo hoặc đăng nhập tài khoản.
5. Sau khi thanh toán khách hàng được chuyển về trang mua hàng.
Mobile Application 1. Khách hàng mua hàng trên ứng dụng đối tác.
2. Chọn MoMo là phương thức thanh toán
3. Ứng dụng đối tác mở ứng dụng MoMo.
4. Khách hàng thực hiện thanh toán trên ứng dụng MoMo.
5. Sau khi thanh toán khách hàng được chuyển về ứng dụng đối tác.
Web In MoMo App 1. Ứng dụng MoMo hiện thị dịch vụ của đối tác trên menu.
2. Khách hàng lựa chọn dịch vụ.
3. Ứng dụng MoMo mở website mua hàng của đối tác ngay trong app (load webview)
4. Khách hàng thực hiện thanh toán trên website.
5. Sau khi khách hàng checkout đơn hàng, MoMo mở màn hình xác nhận thanh toán.
6. Khách hàng xác nhận thanh toán.
7. Thông báo cho user trạng thái đơn hàng của đối tác (Nếu có).
Smart TV/Kiot 1. Khách hàng mua hàng trên Smart TV/Kiot.
2. Chọn MoMo là phương thức thanh toán.
3. Smart TV hiện thị Mã QR của MoMo cung cấp
4. Khách hàng thực hiện thanh toán: Sử dụng ứng dụng MoMo để quét mã QR.
5. Sau khi thanh toán, MoMo thông báo kết quả cho đối tác
6. Smart TV/Kiot hiện thị kết quả giao dịch.
Billing 1. Khách hàng lựa chọn thanh toán tại quầy.
2. Đối tác in hóa đơn có chứa mã QR của MoMo cung cấp.
3. Khách hàng thực hiện thanh toán: Sử dụng ứng dụng MoMo để quét mã QR
4. Sau khi khách hàng thanh toán MoMo thông báo kết quả cho đối tác.
5. Đối tác xử lý và hoàn tất giao dịch cho khách hàng.

Lỗi API

1. Thiếu thông tin đối tác - Mã lỗi 1

Chúng tôi không tìm thấy thông tin cấu hình của bạn.

Tìm thông tin tích hợp được cung cấp cho bạn trong trang MoMo - Doanh Nghiệp

2. Sai thông tin chữ ký - Mã lỗi 5

Chuỗi chữ ký signature được tạo ra trong request không hợp lệ với MoMo

Kiểm tra cách tạo chuỗi chữ ký bao gồm:

3. Đơn hàng đã tồn tại - Mã lỗi 6

Chúng tôi sử dụng mã đơn hàng (orderId) để định danh đơn hàng và nó là duy nhất trong hệ thống MoMo. Nếu đơn hàng đã được tạo thành công sẽ không được tạo lần tiếp theo bất kể trường hợp đơn hàng chưa thanh toán hoặc thanh toán thất bại.

Đối với API hoàn tiền giao dịch orderId cũng là một mã đơn hàng riêng không giống với đơn hàng thanh toán.

Lỗi thanh toán

1. Không nhận được kết quả thanh toán qua phương thức IPN (Instant Notification Payment)

Một yêu cầu IPN sẽ được gửi đi ngay sau khi khách hàng xác nhận giao dịch ở MoMo, nếu không nhận được thông tin này, vui lòng kiểm tra lại tình trạng notifyUrl của bạn.

Hãy chắc chắn rằng:

Nếu bạn đang phát triển ứng dụng trên môi trường local và muốn thử nghiệm tính năng này có thể sử dụng công cụ https://webhook.site hoặc https://ngrok.com/ để kiểm tra thông tin request IPN của MoMo.

2. Lỗi không xác định - Mã lỗi 99

Một giao dịch được đánh dấu trạng thái là không xác định, nguyên nhân có thể là một lỗi hệ thống đã xảy ra trong quá trình xử lý giao dịch hoặc lỗi thanh toán từ nguồn tiền ngân hàng. Nếu bạn nhận được thông tin này hãy liên hệ với chúng tôi để được hỗ trợ.

Tình trạng này cũng có thể xảy ra nếu bạn sử dụng ứng dụng MoMo Production để thực hiện giao dịch trên môi trường testing và ngược lại. Hãy chắc chắn rằng bạn đang sử dụng đúng môi trường.

Test case

Tài liệu để kiểm thử thanh toán thông qua cổng thanh toán của MoMo.

Testcase - V1.0.0

Thanh toán App-In-App

Giới thiệu

Mô tả

Màn hình xác nhận thanh toán đối tác Màn hình xác nhận thanh toán MoMo

Màn hình xác nhận thanh toán phía đối tác (trái) và MoMo (phải)

Cấu hình chung

Mở ứng dụng MoMo

Sử dụng MoMo Mobile SDK để mở ứng dụng MoMo và xác nhận thanh toán

IOS

Xem chi tiết

Android

Xem chi tiết

React Native

Tìm hiểu thêm

Ví dụ một Deeplink

 momo://?action=gettoken&merchantname=CGV Cinemas&amount=99000&merchantcode=CGV01&language=vi&description=Buy ticket&fee=0&ipaddress=192.168.1.154&username=username_accountId@yahoo.com&sdkversion=2.0&appScheme=partnerSchemeId
Attribute Type Bắt buộc Mô tả
action String √ Giá trị là gettoken. KHÔNG THAY ĐỔI
partner String √ Giá trị là merchant. KHÔNG THAY ĐỔI
appScheme String √ partnerSchemeId được cung cấp bởi MoMo
amount int √ Tổng số tiền thanh toán
description String √ Mô tả chi tiết
merchantcode String √ Mã đối tác. Là thông tin partner code
merchantname String √ Tên đối tác
merchantnamelabel String Label để hiển thị tên đối tác trên app MoMo
language String Giá trị là vi. KHÔNG THAY ĐỔI
fee int Phí thanh toán. Mặc định là 0
username String Định danh user (id/email/...)
orderLabel String Label để hiển thị Mã đơn hàng
orderId String Mã đơn hàng đối tác
extra String Thông tin thêm nếu có. Là Json String

Dữ liệu MoMo trả về cho ứng dụng đối tác (MoMo Callback)

MoMo Callback

{
  "status": 0,
  "message": "Success",
  "phonenumber": "0963181714",
  "data": "v2/qml0PbOlrBYjFlZvXwRWjoMpmFmvqStTJt4DCXfE0cgMtyH5Akv+FxL2Nu8lDmxt0P3Mu+YeCGB+UFfwXICo7D07jR6f2VhauglozphNgkK7724sO3qVKC9ZI8KCdr0k4AHuuUNF4AT6Iy2rOmaCVF1WeyS/y/n2E4DArwaHG2J+8StiawfZPiKoUGvywNHV"
}
Attribute Type Description
status int Trạng thái xác nhận đơn hàng (Xem chi tiết ở dưới)
message String Mô tả trạng thái
data String Token thanh toán của MoMo (Nếu status = 0)
phonenumber String Số điện thoại tài khoản MoMo

Các trạng thái của status

Status Description
0 User xác nhận thanh toán thành công
5 Hết thời gian thực hiện giao dịch (Timeout transaction)
6 User huỷ giao dịch

Xử lý thanh toán

Sau khi nhận được token từ app MoMo, server đối tác tạo request và gửi đến server MoMo để yêu cầu treo tiền user.

Request treo tiền mẫu

{
  "customerNumber": "0966787273",
  "partnerCode": "MOMOIQA420180417",
  "partnerRefId": "Merchant123556666",
  "appData": "v2/qml0PbOlrBYjFlZvXwRWjoMpmFmvqStTJt4DCXfE0cgMtyH5Akv+FxL2Nu8lDmxt0P3Mu+YeCGB+UFfwXICo7D07jR6f2VhauglozphNgkK7724sO3qVKC9ZI8KCdr0k4AHuuUNF4AT6Iy2rOmaCVF1WeyS/y/n2E4DArwaHG2J+8StiawfZPiKoUGvywNHV",
  "hash": "A7WFmmnpn6TRX42Akh/iC5DdU5hhBT9LR5QSG6rJAl70hfEkkGUx2pTCai8s+M9KMVUcJ7m52iv74yhmeEjjN10TtEJoqITBIYBG2bqcTprhDijyhV4ePU7ytDNuLxzzIvGfTYyvbsEJ2jZTSf556yod12vhYqOJSFL/U2hVuxjUahf5Rnu5R/OLalg8QmlU6nQooEuNdzEXPMd6j9EaxOCiB2oM5/9QiTN0tCNSTIVvPtnlHu5mIbBHChcwfToIL4IAiD1nbrlDuBX//CZcrZj6hFqjvU31yb/DuG02c3aqWxbZKZ8csOwF9bL30m/yGr/0BQUWgunpDPrmCosf9A==",
  "description": "Thanh toan cho don hang Merchant123556666 qua MoMo",
  "version": 2
}

HTTP Request

Attribute Type Required Description
partnerCode String √ Mã đối tác
partnerRefId String √ Mã đơn hàng phía đối tác
customerNumber String √ Số điện thoại khách hàng MoMo
appData String √ Token nhận được từ app MoMo
hash String √ RSA(jsonString, publicKey).
Xem nội dung jsonString bảng bên dưới
version double √ Phiên bản, hiện tại là 2.0
description String Mô tả cho giao dịch
amount long Số tiền thanh toán

jsonString mẫu

{
  "partnerCode": "MOMOIQA420180417",
  "partnerRefId": "Merchant123556666",
  "partnerTransId": "8374736463",
  "amount": 40000,
  "description": "Thanh toan momo"
}

# Dữ liệu `hash` sau khi áp dụng RSA
"A7WFmmnpn6TRX42Akh/iC5DdU5hhBT9LR5QSG6rJAl70hfEkkGUx2pTCai8s+M9KMVUcJ7m52iv74yhmeEjjN10TtEJoqITBIYBG2bqcTprhDijyhV4ePU7ytDNuLxzzIvGfTYyvbsEJ2jZTSf556yod12vhYqOJSFL/U2hVuxjUahf5Rnu5R/OLalg8QmlU6nQooEuNdzEXPMd6j9EaxOCiB2oM5/9QiTN0tCNSTIVvPtnlHu5mIbBHChcwfToIL4IAiD1nbrlDuBX//CZcrZj6hFqjvU31yb/DuG02c3aqWxbZKZ8csOwF9bL30m/yGr/0BQUWgunpDPrmCosf9A=="


Bảng mô tả nội dung jsonString khi tạo hash bằng RSA

Attribute Type Required Description
amount long √ Số tiền thanh toán
partnerRefId String √ Mã đơn hàng phía đối tác
partnerCode String √ Mã đối tác
partnerName String Tên đối tác
partnerTransId String Mã bổ sung nếu có
description String Mô tả cho giao dịch
customerNumber String Số điện thoại khách hàng
customerName String Tên khách hàng
storeId String Mã cửa hàng (nếu có cửa hàng thì nên truyền để chi tiết hơn)
storeName String Tên cửa hàng

Response mẫu

{
  "status": 0,
  "message": "Thành công",
  "amount": 40000,
  "transid": "43121679",
  "signature": "307b0ee753798e3aff6eb69b2d7966bf0fab29f88336ce0763532fcfafadbe28"
}

HTTP Response

Attribute Type Description
status int Trạng thái giao dịch
message String Nội dung chi tiết
transid String Mã giao dịch MoMo
amount long Số tiền thanh toán
signature String Chữ ký để kiểm tra thông tin. Sử dụng thuật toán Hmac_SHA256 với data theo định dạng: status=$status&message=$message&amount=$amount&transid=$transid

Kết quả thanh toán

Sử dụng field status để xác định trạng thái giao dịch:

Tham khảo bảng mã lỗi để xác định chi tiết lỗi giao dịch.

Xử lý ngoại lệ

Một ngoại lệ sẽ được văng ra nếu có lỗi trong quá trình xử lý giao dịch hoặc lệnh gọi API

Error Response Example

{
  "status": 2400,
  "message": "Dữ liệu sai định dạng.",
  "error": {
    "partnerCode": "not match", //(1)
    "amount": "not match", //(1)
    "hash": "parse fail", // (2)
    "appData": "parse fail" //(3)
  }
}

Mã lỗi: 2400 (Dữ liệu sai định dạng)

Mã lỗi này giống như một HTTP status: 400 với mô tả là dữ liệu được gửi đi không đúng định dạng của server mong muốn hoặc không vượt qua được bước xác thực request.

Mô tả chi tiết lỗi sẽ được chứa trong field error của HTTP Response với định dạng "<fieldName>":"<errorMessage>"

Nó có thể là một hoặc nhiều trong các nguyên nhân sau:

Thanh toán POS

Sơ đồ xử lý

Mô tả

Màn hình chính app MoMo Màn hình Mã thanh toán (QR Code) Màn hình kết quả giao dịch

Xử lý thanh toán

Request treo tiền mẫu

{
  "partnerCode": "MOMOIQA420180417",
  "partnerRefId": "Merchant123556666",
  "description": "thanh toan MoMo POS",
  "hash": "VwnYQbw5eg2XGVO6uGgyOETG9dBQXjdOw8OyBptZ5zvsUTPiNxMc4hi1sd7TTRkifG0kaOJVgplrLlyogFxcegyZzQ7LtjDr/4FtN8MfFKWozhxSWW2JYQyJ/klegGVpOTSkXkfUoueGdTSI2IJFS1pe5rxkmBdMWRilbyfOqbTdrWt50gjY2mQbhke7+9puGLgg8mh+NfYCbEZtHDKyDODA0MVNMNh3ATd31KwfNLm0zx6QQ6KXBq5M04cpTA6rIZ9uz3fxEwTvPycuxJtLvtFDpLapNAmUwqA2Rej3mTgOTN1+Jq9isqEueA0Ix3ip++d8GbJXJYkvYfr0XgT3zA==",
  "version": 2
}

Bảng mô tả request parameter

Tên field Kiểu Bắt buộc Mô tả
partnerCode String √ Mã đối tác
partnerRefId String √ Mã đơn hàng phía đối tác
amount Number √ Số tiền thanh toán
hash String √ RSA(jsonString, publicKey). Xem nội dung jsonString bảng bên dưới
version Number √ Phiên bản, hiện tại là 2.0
description String Mô tả cho giao dịch

jsonString mẫu

{
  "partnerCode": "MOMOIQA420180417",
  "partnerRefId": "Merchant123556666",
  "amount": 30000,
  "paymentCode": "MM627755248085056826",
  "storeId": "001",
  "storeName": "Cua hang doi tac"
}

# Dữ liệu `hash` sau khi áp dụng RSA
"VwnYQbw5eg2XGVO6uGgyOETG9dBQXjdOw8OyBptZ5zvsUTPiNxMc4hi1sd7TTRkifG0kaOJVgplrLlyogFxcegyZzQ7LtjDr/4FtN8MfFKWozhxSWW2JYQyJ/klegGVpOTSkXkfUoueGdTSI2IJFS1pe5rxkmBdMWRilbyfOqbTdrWt50gjY2mQbhke7+9puGLgg8mh+NfYCbEZtHDKyDODA0MVNMNh3ATd31KwfNLm0zx6QQ6KXBq5M04cpTA6rIZ9uz3fxEwTvPycuxJtLvtFDpLapNAmUwqA2Rej3mTgOTN1+Jq9isqEueA0Ix3ip++d8GbJXJYkvYfr0XgT3zA=="


Bảng mô tả nội dung jsonString khi tạo hash bằng RSA

Tên field Kiểu Bắt buộc Mô tả
partnerCode String √ Mã đối tác
partnerRefId String √ Mã đơn hàng phía đối tác
amount Number √ Số tiền thanh toán
paymentCode String √ Mã thanh toán được tạo từ app MoMo mà thu ngân đã quét
storeId String Mã cửa hàng (nếu có cửa hàng thì nên truyền để chi tiết hơn)
storeName String Tên cửa hàng

Response mẫu

{
  "status": 0,
  "message": {
    "transid": 43121679,
    "description": "Thành công",
    "amount": 30000
  }
}

Bảng mô tả response parameter

Tên field Kiểu Mô tả
status Number Kết quả của request. Xem chi tiết
message Json Json chứa nội dung chi tiết
message.description String Mô tả chi tiết
message.transid Number Mã giao dịch MoMo TID (ứng với partnerRefId) được gửi
message.amount Number Số tiền thanh toán

Xác nhận giao dịch

Sau khi MoMo đã treo tiền User thành công (tiền từ ví User được chuyển về ví trung gian), lúc này User sẽ nhận được thông báo thành công (tiền đã được trừ) và giao dịch tương ứng phía MoMo sẽ có trạng thái Chờ xử lý. Đối tác sẽ xử lý các nghiệp vụ nội bộ và gọi API này để hoàn tất giao dịch, gọi là API confirm, bao gồm 2 trạng thái:

Thông tin kết nối đến MoMo

Request mẫu

{
  "partnerCode": "MOMOIQA420180417",
  "partnerRefId": "Merchant123556666",
  "requestType": "capture",
  "requestId": "1512529262248",
  "momoTransId": "12436514111",
  "signature": "307b0ee753798e3aff6eb69b2d7966bf0fab29f88336ce0763532fcfafadbe28",
  "customerNumber": "0963181714"
}


Bảng mô tả request parameter

Tên field Kiểu Bắt buộc Mô tả
partnerCode String √ Mã đối tác
partnerRefId String √ Mã đơn hàng phía đối tác
requestType String √ Loại request, có 2 giá trị:
- Xác nhận (commit) giao dịch: capture
- Hủy bỏ (rollback) giao dịch: revertAuthorize
requestId String √ Id của mỗi request khi gọi qua MoMo
momoTransId String √ Mã giao dịch MoMo TID đã treo tiền ở bước trước
signature String √ Chữ ký để kiểm tra thông tin. Sử dụng thuật toán Hmac_SHA256 với data theo định dạng: partnerCode=$partnerCode&partnerRefId=$partnerRefId&requestType=$requestType
&requestId=$requestId&momoTransId=$momoTransId
customerNumber String Số điện thoại khách hàng
description String Mô tả lý do (sử dụng trong trường hợp rollback)

Response mẫu

{
  "status": 0,
  "message": "Thành công",
  "data": {
    "partnerCode": "MOMOIQA420180417",
    "momoTransId": "12436514111",
    "amount": 30000,
    "partnerRefId": "Merchant123556666"
  },
  "signature": "307b0ee753798e3aff6eb69b2d7966bf0fab29f88336ce0763532fcfafadbe28",
}


Bảng mô tả response parameter

Tên field Kiểu Mô tả
status Number Kết quả của request. Xem chi tiết
message String Mô tả chi tiết
data Json Json chứa nội dung chi tiết (Trong trường hợp thành công)
data.partnerCode String Mã đối tác
data.partnerRefId String Mã đơn hàng phía đối tác
data.momoTransId String Mã giao dịch MoMo TID (ứng với partnerRefId)
data.amount Number Số tiền đã treo
signature String Chữ ký để kiểm tra thông tin. Sử dụng thuật toán Hmac_SHA256 với data là field của data được sắp xếp từ a-z: amount=$amount&momoTransId=$momoTransId&partnerCode=$partnerCode&partnerRefId=$partnerRefId

Thanh toán QR Code

QR Code là mã QR với dữ liệu được tạo ra theo định dạng của MoMo. Sau khi user quét mã và xác nhận thì yêu cầu thanh toán sẽ được gửi đến server MoMo. Có 2 phương thức thanh toán với QR code:

Trong tài liệu này sẽ hướng dẫn cách tạo một QR code động để tích hợp với MoMo.

Sơ đồ xử lý

Mô tả

Tạo QR code

Tạo dữ liệu QR code với định dạng: Domain/pay/store/storeSlug?a=amount&b=billId&s=signature

QR code mẫu

https://test-payment.momo.vn/pay/store/MOMOIQA420180417-store001?a=10000&b=B001221&s=a97c8a08e574a336edbda1e08373a00861dc7a894d09c98a23fd9e834e35645c

Bảng mô tả dữ liệu QR code

Tên field Kiểu Mô tả
Domain String Địa chỉ server MoMo
partnerCode String Mã đối tác
storeId String Mã cửa hàng đối tác
storeSlug String Mã định danh được tạo với định dạng partnerCode-storeId
amount Number Số tiền thanh toán
billId String Mã đơn hàng phía đối tác
signature String Chữ ký để kiểm tra thông tin. Sử dụng thuật toán Hmac_SHA256 với data theo định dạng: storeSlug=$storeSlug&amount=$amount&billId=$billId

Xử lý thanh toán

Sau khi treo tiền thành công, server MoMo sẽ tạo dữ liệu và gọi URL do đối tác cung cấp (confirmUrl) để yêu cầu xác nhận đơn hàng với nội dung mô tả bên dưới.

Request

Confirm URL mẫu

https://partner.com/confirm

Json mẫu

{
  "partnerCode": "MOMOIQA420180417",
  "accessKey": "TNWFx9JWayevKPiB8LyTgODiCSrjstXN",
  "amount": 10000,
  "partnerRefId": "B001221",
  "partnerTransId": "",
  "transType": "momo_wallet",
  "momoTransId": "43121679",
  "status": 0,
  "message": "Thành Công",
  "responseTime": 1555472829549,
  "signature": "a97c8a08e574a336edbda1e08373a00861dc7a894d09c98a23fd9e834e35645c",
  "storeId": "store001"
}
Tên field Kiểu Mô tả
partnerCode String Mã đối tác
accessKey String Thông tin accessKey được mô tả bên trên
amount Number Số tiền đã thanh toán
partnerRefId String Mã đơn hàng phía đối tác
partnerTransId String Thông tin mô tả đơn hàng
transType String Giá trị luôn là momo_wallet
momoTransId String Mã giao dịch MoMo TID
status Number Trạng thái giao dịch. Xem chi tiết
message String Mô tả chi tiết trạng thái
responseTime Number Thời gian gọi confirmUrl tính theo miliseconds
storeId String Mã cửa hàng đối tác
signature String Chữ ký để kiểm tra thông tin. Sử dụng thuật toán Hmac_SHA256 với data theo định dạng: accessKey=$accessKey&amount=$amount&message=$message&momoTransId=momoTransId
&partnerCode=$partnerCode&partnerRefId=partnerRefId&partnerTransId=partnerTransId
&responseTime=$responseTime&status=$status&storeId=$storeId&transType=momo_wallet

Response mẫu

{
  "status": 0,
  "message": "thành công",
  "amount": 10300,
  "partnerRefId": "388064",
  "momoTransId": "987654321",
  "signature": "0sad0fb09dfg8a0480zb80sz98r503480dfb8z0s85030988097g0xcgb8xdzfgs"
}

Response

Server đối tác cần phản hồi lại cho server MoMo biết trạng thái đơn hàng đã được ghi nhận, với nội dung mô tả bên dưới.

Tên field Kiểu Mô tả
status Number Trạng thái đơn hàng. 0 nếu thành công
message String Mô tả trạng thái
partnerRefId String Mã đơn hàng phía đối tác
momoTransId String Mã giao dịch MoMo TID tương ứng
amount Number Số tiền thanh toán
signature String Chữ ký để kiểm tra thông tin. Sử dụng thuật toán Hmac_SHA256 với data theo định dạng: amount=$amount&message=$message&momoTransId=momoTransId&partnerRefId=partnerRefId&status=$status

Tra cứu đơn hàng

Sau khi gửi yêu cầu thanh toán, đối tác có thể dùng API này để kiểm tra thông tin giao dịch bên MoMo như mô tả bên dưới.

Request mẫu

{
  "partnerCode": "MOMOIQA420180417",
  "partnerRefId": "Merchant123556666",
  "description": "kiểm tra trạng thái MoMo",
  "hash": " jClksw/4LI+lMdBHpfX++fYDKpUg4a8W/heOY3PQbxI7NJI3GFlRQGsi70CSTZuW0KKgBXSuvpIFd5zpzzxOi7MJg4qqNWRIEn2/PAiHjB2J6R4w+wdnz9yIAGkN8E9P4l4VAKFfR01quOWjIczjFxT7V8ibOa92dYWtAEtms86Z7QYu4ZIw8m8b1IBgeifxm9T8k5Np3cati0QLUCEFkW+oKEWeV3f3EGpxc7qFed4kPvxZAcBUzzQZHWUBxUVcH7d3tw7n6eGLI6lk+KvFjQRIMr94wvaPpVFXF049wexoUgPri8hUYJyPhEcchZDmeNJUZTWrB/1O1sJLKbSJgQ==",
  "version": 2
}


Bảng mô tả request parameter

Tên field Kiểu Bắt buộc Mô tả
partnerCode String √ Mã đối tác
partnerRefId String √ Mã đơn hàng phía đối tác
hash String √ RSA(jsonString, publicKey). Xem nội dung jsonString bảng bên dưới
version Number √ Phiên bản, hiện tại là 2.0
momoTransId String Mã giao dịch MoMo TID (ứng với partnerRefId) đã được gửi

jsonString mẫu

{
  "partnerCode": "MOMOIQA420180417",
  "partnerRefId": "Merchant123556666",
  "requestId": "8374736463"
}

# Dữ liệu `hash` sau khi áp dụng RSA
"jClksw/4LI+lMdBHpfX++fYDKpUg4a8W/heOY3PQbxI7NJI3GFlRQGsi70CSTZuW0KKgBXSuvpIFd5zpzzxOi7MJg4qqNWRIEn2/PAiHjB2J6R4w+wdnz9yIAGkN8E9P4l4VAKFfR01quOWjIczjFxT7V8ibOa92dYWtAEtms86Z7QYu4ZIw8m8b1IBgeifxm9T8k5Np3cati0QLUCEFkW+oKEWeV3f3EGpxc7qFed4kPvxZAcBUzzQZHWUBxUVcH7d3tw7n6eGLI6lk+KvFjQRIMr94wvaPpVFXF049wexoUgPri8hUYJyPhEcchZDmeNJUZTWrB/1O1sJLKbSJgQ=="


Bảng mô tả nội dung jsonString khi tạo hash bằng RSA

Tên field Kiểu Bắt buộc Mô tả
requestId String √ Id của mỗi request gọi qua MoMo
partnerCode String √ Mã đối tác
partnerRefId String √ Mã đơn hàng phía đối tác
momoTransId String Mã giao dịch MoMo TID (ứng với partnerRefId) được gửi

Response mẫu

{
  "status": 0,
  "messages": "Thành công",
  "data": {
    "status": 1014,
    "message": "Mật khẩu bạn nhập không chính xác.",
    "partnerCode": "MOMOIQA420180417",
    "billId": "Merchant123556666",
    "amount": 30000,
    "discountAmount": 0,
    "fee": 0,
    "phoneNumber": "0938***061",
    "storeId": null,
    "requestDate": "2018-07-12 09:46:32.872",
    "responseDate": "2018-07-12 09:46:33.646",
    "customerName": "DOAN CAO KHANG",
    "transid": 147938695
  }
}


Bảng mô tả response parameter

Tên field Kiểu Mô tả
status Number Kết quả của request.
message String Mô tả chi tiết request
data Json Json chứa thông tin giao dịch phía MoMo
data.status Number Trạng thái của giao dịch. Xem chi tiết
data.message String Mô tả chi tiết trạng thái
data.partnerCode String Mã đối tác
data.billId String Mã đơn hàng phía đối tác (partnerRefId)
data.transid Number Mã giao dịch MoMo TID
data.amount Number Số tiền thanh toán
data.discountAmount Number Số tiền được giảm giá. Trong trường hợp được MoMo giảm giá
data.fee Number Phí giao dịch (tham khảo, mặc định là 0)
data.phoneNumber String Số điện thoại đã thanh toán. Chỉ hiển thị 4 số đầu và 3 số cuối
data.customerName String Tên khách hàng
data.storeId String Mã cửa hàng đối tác
data.requestDate String Thời gian nhận yêu cầu thanh toán
data.responseDate String Thời gian phản hồi cuối cùng

Hoàn tiền giao dịch

MoMo hỗ trợ 2 phương thức refund:

Thông tin kết nối đến MoMo

Request mẫu

{
  "partnerCode": "MOMOIQA420180417",
  "requestId": "1512529262248",
  "hash": "J0PyqdM8Mn8ZJAy8GSe1F/CwI9V4pYE66edb/lxKqRNboWh5eIy203M1xOpfisOmVTRuD5sFDcVXjzWncQHi++75620shnFoh/ZPBqo2kQK8PhMcLjE5+aj+LkQo7ClqYh1o/ZFNDKDSvp2K+YMgMFSpFW3sW7fdamxqMxjQpA0yxUykQg4w0uEzU8ARCak5rcYfWqO9k75zJdKAYZhSrM3l9a2DMZW5G8/PKKa1G+wonLInKiuzCZpf4P2gHNldob2aalBMdqptzlh/nsZ0ALRuXH3GzvWfEFUNZCb/BLqQWBy4840rcjQDFJCa4UP4iXVvzkcV647481Si47TrXQ==",
  "version": 2
}


Bảng mô tả request parameter

Tên field Kiểu Bắt buộc Mô tả
partnerCode String √ Mã đối tác
requestId String √ Id của mỗi request khi gọi qua MoMo
hash String √ RSA(jsonString, publicKey). Xem nội dung jsonString bảng bên dưới
version Number √ Phiên bản, hiện tại là 2.0

jsonString mẫu

{
  "partnerCode": "MOMOIQA420180417",
  "partnerRefId": "Merchant123556666",
  "momoTransId": "147938695",
  "amount": 30000
}

# Dữ liệu `hash` sau khi áp dụng RSA
"J0PyqdM8Mn8ZJAy8GSe1F/CwI9V4pYE66edb/lxKqRNboWh5eIy203M1xOpfisOmVTRuD5sFDcVXjzWncQHi++75620shnFoh/ZPBqo2kQK8PhMcLjE5+aj+LkQo7ClqYh1o/ZFNDKDSvp2K+YMgMFSpFW3sW7fdamxqMxjQpA0yxUykQg4w0uEzU8ARCak5rcYfWqO9k75zJdKAYZhSrM3l9a2DMZW5G8/PKKa1G+wonLInKiuzCZpf4P2gHNldob2aalBMdqptzlh/nsZ0ALRuXH3GzvWfEFUNZCb/BLqQWBy4840rcjQDFJCa4UP4iXVvzkcV647481Si47TrXQ=="


Bảng mô tả nội dung jsonString khi tạo hash bằng RSA

Tên field Kiểu Bắt buộc Mô tả
partnerCode String √ Mã đối tác
partnerRefId String √ Mã đơn hàng phía đối tác
amount Number √ Số tiền cần refund
momoTransId String √ Mã giao dịch MoMo TID (ứng với partnerRefId) được gửi
storeId String Mã cửa hàng (nếu có cửa hàng thì nên truyền để chi tiết hơn)
description String Mô tả lý do cho giao dịch hoàn tiền

Response mẫu

{
  "status": 0,
  "message": "Thành công",
  "transid": 12436514111,
  "amount": 30000,
  "partnerRefId": "Merchant123556666"
}


Bảng mô tả response parameter

Tên field Kiểu Mô tả
status Number Kết quả của request. Xem chi tiết
message String Mô tả chi tiết
partnerRefId String Mã đơn hàng phía đối tác
transid Number Mã của giao dịch refund MoMo
amount Number Số tiền refund

Mô tả mã lỗi

Bảng mô tả các mã lỗi thường gặp.

Status Mô tả
0 Thành công
3 Thông tin tài khoản không tồn tại
4 Chưa đăng ký sử dụng dịch vụ
7 Không có quyền truy cập (khi thanh toán)
8 Sai mật khẩu
9 Mật khẩu hết hạn
11 Mật khẩu nhập sai quá số lần cho phép
13 Mã đặt chỗ không tồn tại
14 Tài khoản người nhận chưa được đăng ký
17 Số tiền không đủ để giao dịch
23 Số tiền quá nhỏ để giao dịch
27 Tài khoản người dùng đã hết hạn sử dụng
32 Yêu cầu thanh toán đã hết hạn
45 Lỗi hệ thống. Request timeout
46 Số tiền vượt quá phạm vi
47 Nhà cung cấp không tồn tại
48 Tài khoản thanh toán không hợp lệ
103 Hủy giao dịch treo tiền
151 Số tiền thanh toán phải nằm trong khoảng (1,000 đến 20,000,000)
153 Giải mã hash thất bại
161 Vướng hạn mức thanh toán. Yêu cầu cài đặt lại hạn mức trên app MoMo
162 Mã thanh toán đã được sử dụng
204 Số tiền sai định dạng
208 Thông tin đối tác không tồn tại hoặc chưa kích hoạt
210 Hệ thống đang bảo trì
403 Không có quyền truy cập (khi kết nối với MoMo)
404 Request không được hỗ trợ
1001 Tài khoản không đủ tiền đề giao dịch
1002 Giao dịch đã được khôi phục
1004 Tài khoản đã hết hạn mức giao dịch trong ngày
1006 Hệ thống xảy ra lỗi
1007 Hệ thống xảy ra lỗi
1013 Xác thực hết hạn
1014 Mật khẩu hoặc mã thanh toán không chính xác
1020 Dữ liệu hoặc tham số không hợp lệ
2117 Mã đơn hàng đã quá hạn
2119 Không lấy được thông tin khuyến mãi
2125 Không thể hoàn tiền giao dịch
2126 Dữ liệu đối tác chưa được cấu hình
2127 Dữ liệu đối tác không đúng
2128 Request ID đã tồn tại
2129 Chữ ký (signature) không khớp
2131 Đơn hàng chưa được khởi tạo hoặc đã quá hạn
2132 Giao dịch đã được xử lý
2133 Hệ thống không thể xử lý yêu cầu thanh toán
2135 Giao dịch thất bại từ phía đối tác
2140 Mã QR đã quá hạn
2400 Dữ liệu sai định dạng
9000 Giao dịch đang được xử lý
9003 Hệ thống tạm ngưng
9043 Tài khoản người dùng cần phải liên kết ngân hàng (theo quy định của ngân hàng nhà nước)

Thông tin Testing

Dành cho developer/tester trên môi trường sandbox(testing)

Ứng dụng MoMo


Scan to download

Tài khoản đăng nhập

Sử dụng tài khoản dưới đây để đăng nhập vào ứng dụng MoMo Testing hoặc Website để thanh toán

Hạn mức 20.000.000 Hạn mức 5.000.000 Thành công Không thành công
0919001000 0918002000 0917003000 0916004000
0919001010 0918002020 0917003030 0916004040
0919001101 0918002200 0917003300 0916004400

Lịch sử cập nhật

Phiên bản 1.0.4 (April 19, 2019)

Phiên bản 1.0.3 (April 11, 2019)

Phiên bản 1.0.2 (February 27, 2019)

Phiên bản 1.0.1 (January 16, 2019)

Phiên bản 1.0

cURL