Please read Onboarding first!!

Version	Date	Author	Description
1.0	24-12-2018	Phuc Dang	Init document
1.1	27-09-2019	Phuc Dang	- Add dateInMillis into STATUS API and NOTIFY PAYMENT. - Add validate callbackUrl in INIT API
1.2	22-11-2019	Vu Huynh	- Modify collection standard document to "payment on MoMo App" and "Payment on Partner Side"
1.3	06-02-2020	Vu Huynh	- Add description for Auto Commit of Collection Services
1.4	23-03-2021	Phuc Bui	- Add Check Status API of Collection Services
1.5	17-03-2022	Sinh Dang	- Modify flow payment, request/response for check info & paybill
1.6	29-03-2022	Linh Hy	- Update flow diagrams, API format
1.7	20-04-2022	Kha Nguyen	- Add resultCode 1208 & 1209
1.8	26-04-2022	Kha Nguyen	- Change dueDate to NOT required. - Update business rule for Check Info API
1.9	29-04-2022	Sinh Dang	- Add field extras in accountInfo and isEditable in billList
1.10	04-05-2022	Kha Nguyen	- Update editable

Table of Content

Check Info
Pay Bill
Check Status

API

1. Check Info

Check Info on Momo App Flow

Purpose: This API allow MoMo fetch the bill information from partner
Method: POST
URL: Depend on partner, provide for MoMo when integrate
Business rule: According to PCI-DSS requirement, in case of paying for credit card, MoMo is not allowed to save customer card information. Therefore, in the first call, MoMo would send 16-digit Primary Account Number (PAN) as value of reference1, partner should response a masked number as description. For later calls, MoMo would send the request with reference1 is masked PAN, reference2 is the value responsed in the first call.

Request:

Parameter

Name	Type	Length	Required	Description
requestId	String	50	x	UUID to uniquely identify this request
reference1	String	50	x	The first key to identify the bill owner, defined by partner
reference2	String	50		The secondary key to identify the bill owner, defined by partner

Example

{
  "requestId": "1511347353577",
  "reference1": "123456789",
  "reference2": "39832848733"
}

Response:

Parameter

Name	Type	Length	Required	Level	Description
requestId	String	50	x	L1	Same with request
resultCode	Integer	4	x	L1	Result Code of request
message	String	200	x	L1	Result message
reference1	String	50	x	L1	reference1 received from request (In case of reference1 is 16-digit Primary Account Number (PAN), return value must be masked follow PCI-DSS requirement 3.3. The maximum that can be displayed are the first six and last four digits)
reference2	String	50		L1	reference2 received from request (In case of reference1 is PAN, please response an identifier as an alias for this PAN. This identifier must ensure idempotency, for each PAN there is only 1 identifier.)
totalAmount	Number	30	x	L1	Total amount of all bills need to be paid. totalAmount = SUM(amount)
accountInfo	JsonObject		x	L1	JSON Object about the Customer/Buyer/Client/CardHolder information
name	String	50	x	L2	Full name
email	String	62		L2	Email address
phoneNo	String	20		L2	Phone number
customerCode	String	30		L2	An ID used by partner to distinguish user
extras	JsonObject			L2	Additional information about Customer/Buyer/Client/CardHolder
billList	JsonArray	10	x	L1	Array contains list of bill needs to be paid, detail of each JSON object as an item is defined below. Maximum 10 items per request.
billId	String	30	x	L2	Unique ID of bill
amount	Number	30	x	L2	Amount of this bill. In case of credit card, this amount value is the Statement Balance
currentBalance	Number	30	x	L2	In case of credit card, this amount value is the Current Balance. Otherwise, please return 0
minimumPayment	Number	30	x	L2	In case of credit card, this value is the Minimum Payment. Otherwise, please return 0
required	Boolean	1	x	L2	- true: this bill is required to be paid by user - false: user could decide to pay for this bill or not
editable	Boolean	1	x	L2	- true: allow user input pay amount manually - false: request user to pay for full amount of bill
dueDate	String	50		L2	Due date to pay for this bill. In case of there is no due date, please return empty. Format: dd/MM/yyyy
description	String	100		L2	Bill description
extras	JsonObject			L2	Extra information for each bill

Example

{
  "requestId": "wqrwpo2343240xsad213",
  "resultCode": 0,
  "message": "Success",
  "reference1": "123456789",
  "reference2": "39832848733",
  "totalAmount": 25000,
  "accountInfo": {
    "name": "Nguyễn Văn A",
    "email": "test@gmail.com",
    "phoneNo": "0987654321",
    "customerCode": "UU-2116530165",
    "extras": {}
  },
  "billList": [
    {
      "billId": "ABCD-0001",
      "amount": 10000,
      "currentBalance": 0,
      "minimumPayment": 0,
      "required": true,
      "editable": true,
      "dueDate": "31/03/2022",
      "description": "Pay for something 1",
      "extras": {}
    },
    {
      "billId": "ABCD-0002",
      "amount": 15000,
      "currentBalance": 0,
      "minimumPayment": 0,
      "required": false,
      "editable": true,
      "dueDate": "01/04/2022",
      "description": "Pay for something 2",
      "extras": {}
    }
  ]
}

Error Code:

Code	Description
0	Success
2	Failed to decrypt
1201	Invalid reference1
1202	Invalid reference2
1203	Data not found
1204	Data expired
1206	Contract/Bill/Loan was terminated
1207	The system is currently unavailable
1208	Authorization error

2. Pay Bill

Payment on Momo App

Purpose: This API allows MoMo to send payment info to partner
Method: POST
URL: Depend on partner, provide for MoMo when integrate

Request:

Parameter

Name	Type	Length	Required	Level	Description
requestId	String	50	x	L1	UUID to uniquely identify this request
reference1	String	50	x	L1	The same response reference1 of check info
reference2	String	50		L1	The same response reference2 of check info
totalAmount	Number	30	x	L1	Total amount of transaction for all paid bill
transactionId	String	50	x	L1	MoMo transaction ID
transactionTimestamp	String	50	x	L1	Date and time in UTC that the transaction was created
billList	JsonArray	10	x	L1	List of bill are paid.
billId	String	30	x	L2	Unique ID of paid bill.
amount	Number	30	x	L2	Amount of this bill.

Example


{
  "requestId": "2300699797",
  "reference1": "123456789",
  "reference2": "39832848733",
  "totalAmount": 25000,
  "transactionId": "2300699797",
  "transactionTimestamp": "2019-04-01T10:49:45+0700",
  "billList": [
    {
      "billId": "Bill_01",
      "amount": 10000
    },
    {
      "billId": "Bill_02",
      "amount": 15000
    }
  ]
}

Response:

Parameter

Name	Type	Length	Required	Level	Description
requestId	String	50	x	L1	Same with request
resultCode	Number	4	x	L1	Result code of request
message	String	200	x	L1	Result message
partnerPaymentId	String	50		L1	Unique ID for payment transaction from partner

Example

{
  "requestId": "2300699797",
  "resultCode": 0,
  "message": "Success",
  "partnerPaymentId":"DS-5216516513531"
}

Error Code:

Code	Description
0	Success
1	Failed
2	Failed to decrypt
1201	Invalid reference1
1202	Invalid reference2
1203	Data not found
1204	Data was expired
1206	Contract/Bill/Loan was terminated
1207	The system is currently unavailable
1208	Authorization error
1209	Paid amount is not correct

3. Check Status (Optional)

Purpose: MoMo will use this API to get final status of payment in partner system
Method: POST
URL: Depend on partner, provide to Momo when integrate

Request:

Parameter

Name	Type	Length	Required	Description
requestId	String	50	x	UUID to uniquely identify this request
transactionId	String	50	x	MoMo transaction ID

Example

{
  "requestId": "123e4567-e89b-12d3-a456-426614174000",
  "transactionId": "2300699797"
}

Response:

Parameter

Name	Type	Length	Required	Level	Description
requestId	String	50	x	L1	Same with request
resultCode	String	50	x	L1	Result code
message	String	500	x	L1	Description

Example

{
  "requestId": "123e4567-e89b-12d3-a456-426614174000",
  "resultCode": 0,
  "message": "Success"
}

Error Code:

Code	Description
0	Success, MoMo payment transaction has been processed in system
2	Decryption Fail
1201	Data not found
1202	Data expired
1207	The system is currently unavailable

4. Reconciliation

All transaction on Momo's reconcile are final result. MoMo provides ways to reconcile: 1. Portal web(M4b): Can query/export transactions realtime. 2. SFTP: Export transactions according time config.