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 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:
- Bước 1: Đăng ký tài khoản doanh nghiệp.
- Bước 2: Lựa chọn hình thức mong muốn.
- Bước 3: Tiến hành tích hợp theo tài liệu được cung cấp.
- Bước 4: Tiến hành kiểm thử trên môi trường Test.
- Bước 5: Tiến hành kiểm thử trên môi trường Production.
- Bước 6: Hoàn thiện và đưa vào sử dụng.
Các hình thức tích hợp thanh toán:
- Sử dụng Cổng thanh toán MoMo (All In One)
- Thanh toán App-In-App: Áp dụng cho đối tác có ứng dụng di động (android/ios) muốn mở trực tiếp ứng dụng MoMo để thanh toán.
- Thanh toán POS: Áp dụng cho đối tác có hệ thống bán hàng bằng máy POS. Thu ngân dùng máy scan để quét "MÃ THANH TOÁN" trên app MoMo để thanh toán
- Thanh toán QR Code: Đối tác tạo QR code theo định dạng MoMo cung cấp, khách hàng chỉ cần dùng app MoMo để quét và 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. 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.
3. 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
/orderId
.
4. 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.
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, signature
sẽ được tạo ra với key là secretKey
và data 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.vnSandbox: https://test-payment.momo.vn |
Firewall (Nếu cần)
Môi trường | Incoming | Outcoming |
---|---|---|
Sandbox | 210.245.113.71 | 115.78.237.157 |
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
- Bước 1: Khách hàng kiểm tra đơn hàng và chọn MoMo là phương thức thanh toán
- Bước 2: Server của bạn tạo session thanh toán và gửi yêu cầu thanh toán qua MoMo
- Bước 3: Chuyển trang mua hàng sang trang thanh toán của MoMo.
- Bước 4: Khách hàng sử dụng ứng dụng MoMo để quét mã QR hoặc đăng nhập để thanh toán
- Bước 5: Sau khi thanh toán MoMo sẽ chuyển khách hàng về trang mua hàng
- Bước 6: Server của bạn xác thực giao dịch và cập nhập dịch vụ cho khách hàng
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ánMin: 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 | √ | URL được sử dụng để chuyển trang từ MoMo về trang mua hàng của đối tác sau khi khách hàng thanh toán |
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¬ifyUrl=$notifyUrl&extraData=$extraData |
extraData |
String | √ | Thông tin bổ sung theo định dạng: <key>=<value>;<key>=<value> |
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
payUrl
: Sử dụng URL này để chuyển từ trang mua hàng của đối tác sang trang thanh toán của MoMoqrCodeUrl
: Sử dụng data này để tạo mã QR nếu bạn muốn khách hàng quét mã QR trực tiếp trên trang mua hàng nếu không muốn chuyển sang thanh toán của MoModeeplink
: Sử dụng URL này để mở ứng dụng MoMo (Khách hàng phải cài đặt ứng dụng MoMo) và trang xác nhận thanh toán. Áp dụng trên ứng dụng mobile hoặc mobile web của đối tácdeeplinkWebInApp
: Sử dụng URL này để mở màn hình xác nhận thanh toán của ứng dụng MoMo. Áp dụng khi website của đối tác nhúng vào ứng dụng MoMo
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
MoMo website sẽ chuyển về trang mua hàng dựa vào field returnUrl
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 POST
/application/x-www-form-urlencoded
tới máy chủ đối tác
Thông tin tham số (Request - IPN/Redirect)
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)
Key | Value |
---|---|
Content-Type | application/json;charset=UTF-8 |
Http Status Code | 200 |
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 |
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 |
Trạng thái giao dịch
Sử dụng field errorCode
để xác định trạng thái giao dịch:
- Nếu
errorCode = 0
giao dịch đã thanh toán thành công - Nếu
errorCode <> 0
giao dịch xử lý thất bại
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 ý
- 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 - 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. - Luôn xử lý API
notifyUrl
để xử lý kết quả. Khắc phục trường hợp trình duyệt bị đóng hoặc không thể chuyển trang.
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 | √ | web hoặc qr |
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 |
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 |
int | √ | 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 |
int | √ | 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 |
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 | OTP expired | Mã xác thực hết hạn |
99 | Error undefined | Lỗi không xác định |
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
https://test-payment.momo.vn/gw_payment/test_momo_pay
- Bước 1: Tạo yêu cầu thanh toán qua cổng thanh toán MoMo (lấy
payURL
) - Bước 2: Chuyển trang mua hàng sang trang thanh toán MoMo
- Bước 3: Sử dụng ứng dụng MoMo (testing) quét mã QR hoặc đăng nhập để thanh toán
Các đối tác của MoMo đang sử dụng:
- NhacCuaTui: https://www.nhaccuatui.com/nhaccuatui-vip/mua-vip
- The Coffee House: https://order.thecoffeehouse.com/
Lịch sử cập nhập
Phiên bản 1.0
- Cập nhập mã lỗi 49
Phiên bản 1.0.1 (January 16, 2019)
- Cập nhật mã lỗi 12, 14, 33, 37, 38, 44, 63, 80.
Thanh toán App-In-App
1. Sơ đồ xử lý
2. Mô tả
- Bước 1: Ứng dụng của đối tác sử dụng MoMo Mobile SDK để mở ứng dụng MoMo yêu cầu thanh toán
- Bước 2: Sau khi xác nhận thanh toán ở MoMo, MoMo sẽ mở lại ứng dụng đối tác
- Bước 3: Ứng dụng đối tác sử dụng thông tin callback của ứng dụng MoMo để gửi thông tin thanh toán lên server đối tác
- Bước 4: Server đối tác xác thực và gửi yêu cầu thanh toán đến server MoMo
- Bước 5: Server MoMo xử lý và trả kết quả cho server đối tác, đồng thời thông báo tới app MoMo
- Bước 6: Đối tác xử lý và trả kết quả thanh toán cho người dùng
Màn hình xác nhận thanh toán phía đối tác (trái) và MoMo (phải)
3. Cấu hình chung
- partnerSchemeId để mở app MoMo: sử dụng IOS SCHEME ID
- Giao diện trên app:
- Tiêu đề MoMo (bắt buộc): English = "MoMo e-wallet", Vietnamese = "Ví MoMo"
- Icon MoMo: https://img.mservice.io/momo-payment/icon/images/logo512.png
- Mã màu (tuỳ chọn): #b0006d
4. Mở ứng dụng MoMo
Sử dụng MoMo SDK Mobile để mở ứng dụng MoMo và xác nhận thanh toán
IOS
- Bước 1: Cấu hình file Plist
- CFBundleURLTypes: xem
partnerSchemeId
phía trên - LSApplicationQueriesSchemes: luôn là
momo
- CFBundleURLTypes: xem
- Bước 2: Import SDK AppDelegate instance
- Bước 3: Đăng ký và xử lý callback từ MoMo
Android
- Bước 1: Import SDK thêm JitPack repository vào file
build.gradle
- Bước 2: Cấu hình AndroidMainfest
- Bước 3: Tạo Activity cho nút Thanh toán
- Bước 4: Nhận callback từ app MoMo
Tham số tạo deeplink mở app MoMo
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
Tên field | Kiểu | 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)
Tên field | Kiểu | Mô tả |
---|---|---|
status |
int | Trạng thái xác nhận đơn hàng hay khô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 |
Trạng thái MoMo Callback
Status | Mô tả |
---|---|
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 |
5. Xử lý thanh toán MoMo
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 thanh toán
POST
/pay/app
Request 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
}
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 |
customerNumber |
String | √ | Số điện thoại khách hàng |
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 |
Number | √ | Phiên bản, hiện tại là 2.0 |
description |
String | Mô tả cho giao dịch | |
amount |
Number | 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
Tên field | Kiểu | Bắt buộc | Mô tả |
---|---|---|---|
amount |
Number | √ | 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"
}
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 | Nội dung chi tiết |
transid |
String | Mã giao dịch MoMo TID (ứng với partnerRefId ) được gửi |
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: status=$status&message=$message&amount=$amount&transid=$transid |
Thanh toán POS
1. Sơ đồ xử lý
2. Mô tả
- Bước 1: User đăng nhập app MoMo, chọn tính năng MÃ THANH TOÁN để tạo mã thanh toán (
paymentCode
) - Bước 2: Thu ngân quét Bar code hoặc QR code trên màn hình user và thông tin được gửi đến server POS đối tác
- Bước 3: Server POS đóng gói và gửi thông tin giao dịch nhận được đến server MoMo
- Bước 4: Server MoMo xử lý giao dịch và trả kết quả về cho server POS
3. Xử lý thanh toán
POST
/pay/pos
Request 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 |
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:
- QR Tĩnh: MoMo sẽ tạo ra theo thông tin trên trang tài khoản danh nghiệp (M4B). Đối tác sử dụng QR này đặt ở cửa hàng của mình, khi user quét sẽ nhập số tiền cần phải thanh toán.
- QR Động: Còn gọi là QR code trên bill. Đối tác tạo ra theo định dạng của MoMo (mô tả bên dưới) và in lên bill/màn hình cho user quét.
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.
1. Sơ đồ xử lý
2. Mô tả
- Bước 1: User yêu cầu thanh toán bằng QR code MoMo
- Bước 2: Cửa hàng tạo ra QR code theo định dạng của MoMo
- Bước 3: Cửa hàng in hóa đơn có kèm theo QR code đã tạo để user quét
- Bước 4: User quét và xác nhận thanh toán
- Bước 5: Server MoMo xử lý và trả kết quả về cho server đối tác
- Bước 6: Thu ngân kiểm tra lại thông tin từ kết quả của user và server đối tác
3. 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 (https://test-payment.momo.vn ) |
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 |
4. Xử lý kết quả thanh toán
Sau khi MoMo xử lý xong, nếu đối tác có nhu cầu, server MoMo sẽ gọi về 1 URL do đối tác cung cấp (notifyUrl
) để thông báo trạng thái đơn hàng với param mô tả bên dưới.
Request
Notify URL mẫu
https://partner.com/notify?partner_code=MOMOIQA420180417&access_key=TNWFx9JWayevKPiB8LyTgODiCSrjstXN&amount=10000&order_id=B001221&order_info=&order_type=momo_wallet&transaction_id=43121679&status_code=0&message=Thành công&response_time=Tue Jan 08 10:49:23 ICT 2019&store_id=store001&signature=a97c8a08e574a336edbda1e08373a00861dc7a894d09c98a23fd9e834e35645c
- Method:
POST
- Content-type:
application/x-www-form-urlencoded
- Param: Request param (xem bảng dưới)
Tên field | Kiểu | Mô tả |
---|---|---|
partner_code |
String | Mã đối tác |
access_key |
String | Thông tin accessKey được mô tả bên trên |
amount |
String | Số tiền đã thanh toán |
order_id |
String | Mã đơn hàng phía đối tác |
order_info |
String | Thông tin mô tả đơn hàng |
order_type |
String | Giá trị luôn là momo_wallet |
transaction_id |
String | Mã giao dịch MoMo TID |
status_code |
String | Trạng thái giao dịch. Xem chi tiết |
message |
String | Mô tả chi tiết trạng thái |
response_time |
String | Thời gian gọi notifyUrl |
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: partner_code=$partner_code&access_key=$access_key&amount=$amount&order_id=$oder_id &order_info=$order_info&order_type=momo_wallet&transaction_id=$transaction_id &message=$message&response_time=$response_time&status_code=$status_code |
store_id |
String | Mã cửa hàng đối tác |
Response mẫu
{
"status": 0,
"message": "Thành công",
"momoTransId": "43121679",
"billId": "B001221",
"amount": "30000"
}
Response
Nếu thành công, server đối tác cần phản hồi lại cho server MoMo biết đơn hàng đã được ghi nhận, với thông tin
- HTTP status:
200
- Body:
application/json
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 |
billId |
String | Mã đơn hàng phía đối tác |
momoTransId |
String | Mã giao dịch MoMo TID tương ứng |
amount |
String | Số tiền thanh toán |
Thanh toán Tokenization
Tài liệu này đang trong quá trình xây dựng.
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.
POST
/pay/query-status
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. Xem chi tiết |
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
:
- Partial refund: refund lại 1 phần số tiền đã giao dịch khi số tiền refund nhỏ hơn số tiền đã thanh toán
- Full refund: refund toàn bộ số tiền đã giao dịch khi số tiền refund bằng số tiền đã thanh toán
Thông tin kết nối đến MoMo
POST
/pay/refund
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 |
Xác nhận giao dịch
Xác nhận (confirm
) hoặc hủy bỏ (rollback
) giao dịch đã được treo tiền trước đó.
Thông tin kết nối đến MoMo
POST
/pay/confirm
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 | √ | Type của request, có 2 giá trị: - Xác nhận giao dịch: capture - Hủy bỏ 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 (ứng với partnerRefId ) |
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 | |
notifyType |
String | Type của noti sẽ bắn vào app MoMo: - Mặc định: 0 (không bắn)- Noti thanh toán thành công: 1 (hiện không sử dụng do đã bắn tại bước treo tiền)- Noti sau khi confirm /rollback thành công: 2 |
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 |
Mô tả mã lỗi
Các mã lỗi này là mã thường gặp trong quá trình tích hợp, ngoài ra có thể xuất hiện mã mà không có trong danh sách này.
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 |
Thông tin Testing
Dành cho developer/tester trên môi trường sandbox/testing
Ứng dụng MoMo
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
Key | Type |
---|---|
Số điện thoại | 0961800390; 0900123123; 0978787890; 0978787891; 0978787892; 0900123124; 0900123125; 0900123126; 0900123127; 0900123128; 0978787899 |
Mật khẩu | 000000 |
Mã xác thực (OTP) | 000000 |
Tài khoản doanh nghiệp
Login môi trường test với thông tin sau:
- Username: mm_bu_test
- Password: MOMO2018
- Access key (không sử dụng cho tích hợp Cổng thanh toán MoMo): TNWFx9JWayevKPiB8LyTgODiCSrjstXN
Truy cập vào trang thông tin tích hợp để lấy thông như bên dưới:
- Partner code: MOMOIQA420180417
- Secret key: PPuDXq1KowPT1ftR8DvlQTHhC03aul17
C# RSA format key
<RSAKeyValue>
<Modulus>kpa+qMXS6O11x7jBGo9W3yxeHEsAdyDE40UoXhoQf9K6attSIclTZMEGfq6gmJm2BogVJtPkjvri5/j9mBntA8qKMzzanSQaBEbr8FyByHnf226dsLt1RbJSMLjCd3UC1n0Yq8KKvfHhvmvVbGcWfpgfo7iQTVmL0r1eQxzgnSq31EL1yYNMuaZjpHmQuT24Hmxl9W9enRtJyVTUhwKhtjOSOsR03sMnsckpFT9pn1/V9BE2Kf3rFGqc6JukXkqK6ZW9mtmGLSq3K+JRRq2w8PVmcbcvTr/adW4EL2yc1qk9Ec4HtiDhtSYd6/ov8xLVkKAQjLVt7Ex3/agRPfPrNw==</Modulus>
<Exponent>AQAB</Exponent>
</RSAKeyValue>
- Public key:
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAkpa+qMXS6O11x7jBGo9W3yxeHEsAdyDE40UoXhoQf9K6attSIclTZMEGfq6gmJm2BogVJtPkjvri5/j9mBntA8qKMzzanSQaBEbr8FyByHnf226dsLt1RbJSMLjCd3UC1n0Yq8KKvfHhvmvVbGcWfpgfo7iQTVmL0r1eQxzgnSq31EL1yYNMuaZjpHmQuT24Hmxl9W9enRtJyVTUhwKhtjOSOsR03sMnsckpFT9pn1/V9BE2Kf3rFGqc6JukXkqK6ZW9mtmGLSq3K+JRRq2w8PVmcbcvTr/adW4EL2yc1qk9Ec4HtiDhtSYd6/ov8xLVkKAQjLVt7Ex3/agRPfPrNwIDAQAB