MOMO PAY ROLL API

Specification Doc

Version	Date	Author	Description
1.0	16-04-2018	Phong Le	Created
1.1	06-2018	Phuc Dang	Update api complete

Index

• Introductions
• Flows
• Methods
  • Common
  • 1. CheckWallet
  • 2. Check Persional ID
  • 3. Pay roll
  • 4. Notify Result : one by one
  • 5. Check status
  • 6. Check transaction
  • 7. Get Trans
• Error Code

Introductions

This document describes the API methods that partner uses to interact with the Momo. - Interaction happens over HTTPS using POST requests. - Each method accepts a single request stream and returns a single response stream. - Once decrypted, request and response streams are JSON formatted.

Momo provide the following data to Partner: - Base url of the endpoints that partner will hit - SSL Certificate - PGP public key for Partner to encrypt the body - partner code Partner needs to provide to Service Provider: - PGP public key for Momo to encrypt the body

Flows

Methods

Common

• All APIs exposed are RESTful API’s with request and response payloads formatted as JSON.
• Body data after decrypt is a JSON
• All request and response include these field:

Header

Key	Values
Content-type	application/pgp-encrypted
Accept	application/pgp-encrypted
partner-code	Momo will provide when integrate

Sample Raw message before decrypt:

-----BEGIN PGP MESSAGE-----  
Version: GnuPG v2.0.14 (GNU/Linux)

hQEMAzCLjonquyAfAQf/XwqTeJL7z5H7JRs5Th8aJhiO0P+AI7dr8abPTTV2j35P
541JnBrIYn+Ee1phRmxWe7BBNPjSpQTd7y+k2eArAmk8TLIZmVKcIr9QfjdtKhjT
HFp2FircA5s3uzHh2jauT8vV3XhQHd2mrdUovlVlMuMdlwhHDXxi+6ZVOf7L1oOM
0duHbQZCV/qcantgN8P6tWTlE/aMyFp+sijoLpCyZ5RTbQG/tnUdddgNLBU/Ivwm
TNX8GVdDp1gnOi48gwbllQq0TjlZVhBt3aUN7tK8yONWVfwTFoplHr9Yc5RK3WJv
SAwpHFUe2sWpNFyfLKHgb2du0yzls3BL7iRmVF21sdLpAdQ99m0N7rYBzEzrXp9Y
URXqo+FRjLZbYBoS5XoNMUaN9ACHmchPtd1uiwRE3S5n07DEQEoblq1wR6w1mK7e
vh3w+TvdUTJhu9EMIMLxNU37meUJeuso3S6Ly8E356QvLTgCEjS1gQiAwQDeyGbD
NYDBlGvQC2euJMfCUfSOUL9hkqi2UItgNmIF4znXLF1OsdWqK08n44H+9vcMlSh1
Lq8IQWLu56T/ft7+2GNrQ9hAgEMMr1rMYSLP5Go5/JxvFCoaUADY0GE70oXR2+K1
7Hbw+VvYVsrJwALbcBKnmH8kzmHq+2KNkwgTcA30javdMj/9aOQtcwP4ZOICQi+W
4KrND/uT3UxRS9DDuF+B+LZPVPE5s8qdT98CKrQ9oeqZ8Kfw5gELCXy6HiixccfK
eCSY0xEP5Vl6/fmeS5GBUNJWjFUi7Wi8+GXbmvgb7QTm+EFU9UFV9dsUCArRxf8z
8rIz7wAPtTx0Vn0Ux70PKiEpA2CqpzqviERQ1uym5kPdbpL5nDT7kMzsnM8Hplym
ovrTTjhOlTKzr60d3nZV9WU4r+c8FUYdSvnFAD2Vys3pUpmV7Rokl1eI6dt0zBUh
V7nWqUjgJi6/z4vgpNmFxeKHMN0+Hd9VwnL3v+RJbgBx2A+EyRj8Re+xGGIWMGZ+
UpfSfKIcPeyt+qVsO/YBsLR6jTn0DASax9wSkP/4VQzfVYRY2FdF9wLoRNBPw7hk
mtu6zfgxFX/R25iRMbN/xjrdlxzvJG5zlooaSS8rI2xGNgyhBimB7Ha9KwtC2Snr
IIY2sfDa5W/br/oNNEME+c5oEF+soVADZOLQ2wcRzMlPehyCckGCdAAmX14=
=OnzF  
-----END PGP MESSAGE-----

1. CheckWallet

Allow partner check status of wallet

Request

• Method: POST
• URL: api/payroll/check-wallet

Name	Type	Description
requestId	String	Unique String for each request
walletId	String	walletId that need to check (msisdn)

Response

Name	Type	Description
requestId	String	Same with request
resultCode	Integer	Result Code of request
message	String	Result message
referenceId	String	Unique for each response

Example:

Request

{
    "requestId": "wqrwpo2343240xsad213",
    "walletId": "0902890666"
}

Response

{
    "requestId": "wqrwpo2343240xsad213",
    "resultCode": 0,
    "message": "Success",
    "referenceId": "sdfsfsdfdggfgf"
}

Result Code

Code	Message	Status
0	success	Success
4	Invalid wallet Id	Failed
1006	Wallet don't identity	Failed
1007	Wallet is locked	Failed
1008	Wallet isn't existed	Failed
1016	Wallet is destroyed	Failed
1017	Reject by MoMo rule	Failed

2. Pay roll

Partner send list of requests need to pay roll

Request

• Method: POST
• URL: api/payroll/pay

Note: - This function will receive requests, record requests and return the result immediate, and will notify the result after execute - Process transfer one by one, every the transfer to wallet have a corresponding resultCode - New balance = sum ( current balance of wallet and amount need to transfer ) - When new balance more than balance allowed then reject transfer for those wallet

STT	Name	Type	Level	Require	Description
1	requestId	String	L1	Yes	Unique String for each request
2	walletIds	JsonArray	L1	Yes	List Momo wallet id (phone number) need to transfer money to.
	walletId	String	L2	Yes	Momo wallet id (phone number) need to transfer money to.
	amount	Number	L2	Yes	Amount need to payment
	walletName	String	L2	No	Wallet holder name
	personalId	String	L2	No	Personal Id
	description	String	L2	No	description
3	TotalAmount	Number	L1	Yes	Total Amount need to payment
4	createdDate	String	L1	Yes	created date (YYYY-MM-DDThh:mm:ssTZD) Ex: 2017-03-06T19:20:30+07:00
5	description	String	L1	No	description

Response

Name	Type	Description
requestId	String	Same with request
resultCode	Integer	Result Code of request 0: success Other: fail
referenceId	String	Unique for each response
message	String	Result message

Example

Request

{
    "requestId": "wqrwpo2343240xsad213",
    "walletIds": [
        {
        "walletId": "0903412001",
        "amount": 10000000,
        "walletName": "Nguyen van B",
        "persionalId": "023456789",
        "description": "desc"
        },
        {
        "walletId": "0903412002",
        "amount": 12000000,
        "walletName": "nguyen van A",
        "persionalId": "023456789",
        "description": "desc"
        }
    ],
    "totalAmount": 40000000,
    "description": "test desc",
    "createDate": "yyyy-MM-dd HH:mi:ss.ZZZ"
}

Response

{
    "requestId": "wqrwpo2343240xsad213",
    "referenceId": "2313_e3w24_ddqwdq_dasdasda",
    "resultCode": 1001,
    "message": "test message response"
}

3. Notify Result : one by one

Partner will provide the API so that Momo can invoke with this fields

Request

• Method: POST
• URL: Get from payment request
• Header:

Key	Value
Content-type	application/json

Name	Type	Level	Description
requestId	String	L1	Unique String for each request
paymentId	String	L1	The same requestId when partner send to Momo
message	String	L1	Result message
createdDate	String	L1	yyyy-MM-dd HH:mi:ss.ZZZ
walletId	String	L1	Momo wallet id (phone number) need to transfer money to.
amount	Number	L1	Amount need to payment
amountAccepted	Number	L1	Amount already transfer
resultCode	String	L1	Result Code for every transfer
paymentRef	String	L1	Using for report

Response

Name	Type	Description
requestId	String	Same with request
resultCode	Number	Result Code of request
referenceId	String	Unique for each response
message	String	Result message

Example

Request

{
    "requestId": "wqrwpo2343240xsad213",
    "paymentId": "dsadaad213",
    "createdDate": "2017-03-16 15:05:05.231",
    "message": "sdfsd sfdsfs",
    "walletId": "0903412002",
    "amount": 12000000,
    "amountAccepted": 12000000,
    "resultCode": "0",
    "paymentRef": "1234567890125"
}

4. Check trans

Allow partner check a transaction

Request

• Method: POST
• URL: api/payroll/check-tran

Name	Type	Description
requestId	String	Unique String for each request
paymentRef	String	Payment id that need to check

Response

Name	Type	Description
requestId	String	Same with request
resultCode	Integer	Result Code of request
referenceId	String	Unique for each response
message	String	Result message
data	JsonObject	Data is the same with data of the response of function that want to check

Example

Request

{
    "requestId": "wqrwpo2343240xsad213",
    "paymentRef": "123456"
}

Response

{
    "requestId": "wqrwpo2343240xsad213",
    "referenceId": "2313_e3w24_ddqwdq_dasdasda",
    "resultCode": 0,
    "message": "Success",
    "data": {
        "requestId": "wqrwposs2343240xsad213",
        "referenceId": "2313_e3w24_w432423_dasdasda",
        "resultCode": 0,
        "message": "Success"
    }
}

5. Check status

Allow partner get check status of confirm request

Request

• Method: POST
• URL: api/payroll/status

Name	Type	Description
requestId	String	Unique String for each request
checkRequestId	String	Payment id that want to check

Response

Name	Type	Level	Description
requestId	String	L1	Same with request
referenceId	String	L1	Unique for each response
resultCode	Integer	L1	Result Code of request
message	String	L1	Result message
data	JsonArray	L1
walletId	String	L2	Momo wallet id (phone number) need to transfer money to.
amount	Number	L2	Amount need to payment
amountAccepted	Number	L2	Amount already transfer
paymentRef	String	L2	Using for report
resultCode	String	L2	Result Code for every transfer
message	String	L2	Result message

Example

Request

{
    "requestId": "wqrwpo2343240xsad213",
    "password": "12345678",
    "paymentId": "12343465656343werw"
}

Response

{
    "requestId": "wqrwpo2343240xsad213",
    "referenceId": "2313_e3w24_ddqwdq_dasdasda",
    "resultCode": 0,
    "message": "Success",
    "data": [
        {
            "walletId": "0903412001",
            "amount": 10000000,
            "amountAccepted": 10000000,
            "resultCode": "0",
            "paymentRef": "1234567890123",
            "message": "dshduashkcnkuz"
        },
        {
            "walletId": "0903412002",
            "amount": 12000000,
            "amountAccepted": 12000000,
            "resultCode": "0",
            "paymentRef": "1234567890124",
            "message": "dshduashkcnkuz"
        }

    ]
}

6. Get Trans

Allow partner get all transaction of the day

Request

• Method: POST
• URL: api/payroll/get-trans

Name	Type	Description
requestId	String	Unique String for each request
date	String	Date to get all trans (yyyy-MM-dd)

Response

Name	Type	Level	Description
requestId	String	L1	Same with request
referenceId	String	L1	Unique for each response
resultCode	Integer	L1	Result Code of request
message	String	L1	Result message
data	JsonArray	L1	Array of JsonObject include these information
requestId	String	L2	Transfer request id
walletIds	String	L2	Momo wallet Id (mobile phone)
walletId	String	L3	Momo wallet id (phone number) need to transfer money to.
amount	Number	L3	Amount need to payment
amountAccepted	Number	L3	Amount already transfer
resultCode	String	L3	Result Code for every transfer
paymentRef	String	L3	Using for report

Example

Request

{
    "requestId": "wqrwpo2343240xsad213",
    "password": "12345678",
    "date": "2017-12-04"
}

Response

{
    "requestId": "wqrwpo2343240xsad213",
    "referenceId": "2313_e3w24_ddqwdq_dasdasda",
    "resultCode": 0,
    "message": "Success",
    "data": [
        {
            "requestId": "wqrwpo2343240xsad213",
            "walletIds": [
                {
                    "walletId": "0903412001",
                    "amount": 10000000,
                    "amountAccepted": 10000000,
                    "resultCode": "0",
                    "paymentRef": "1234567890123"
                },
                {
                    "walletId": "0903412002",
                    "amount": 12000000,
                    "amountAccepted": 12000000,
                    "resultCode": "0",
                    "paymentRef": "1234567890124"
                }
            ]
        },
        {
            "requestId": "wqrwpo2343240xsad214",
            "walletIds": [
                {
                    "walletId": "0903412003",
                    "amount": 10000000,
                    "amountAccepted": 10000000,
                    "resultCode": "0",
                    "paymentRef": "1234567890125"
                },
                {
                    "walletId": "0903412004",
                    "amount": 12000000,
                    "amountAccepted": 12000000,
                    "resultCode": "0",
                    "paymentRef": "1234567890126"
                }
            ]
        }
    ]
}

Error Code

Apply for all API that Momo provide

Code	Message	Function	Status
0	success	All	Success
2	Cannot decrypt message	All	Fail
4	Invalid wallet Id	payment	Fail
8	Duplicate request Id	All	Fail
9	Invalid partner code	All	Fail
10	Unknown result.	All	Check by hand, or call check status to get the final result
11	Other error	All	Fail
1001	Invalid amount	All	Fail
1002	Reject by Momo rule	Confirm	Fail
1003	Payment Id not found	status	Fail
1004	Invalid date	All	Fail
1005	Over balance of receiver	Payout	Fail
1006	Wallet don't identity	All	Fail
1007	Wallet is locked	All	Fail
1008	Not existed walletId of receiver.	All	Fail
1009	Invalid national id of receiver	All	Fail
1010	Invalid name of receiver	All	Fail
1011	Param verifyOtpUrl is null or empty	All	Fail
1012	Param notifyUrl is null or empty	All	Fail
1013	Param checkSumKey is null or empty	All	Fail
1014	Param rejectIfOverBalance is null or empty	All	Fail
1015	Partner system error	All	Fail
1016	Wallet is detroyed	All	Fail
1017	Reject by pauyroll rule	All	Fail
1018	Reject by payout rule (sms)	All	Failed
1019	Reject by payout rule (noti)	All	Failed
1020	Invalid password to check (the password use for : get transaction, check wallet, check personal id)	get-trans, checkwallet, check-personal-id	Failed