MoMo On Delivery

Process Flow

Usecase 1: QR Code attached on the parcel

Before shipping

• Step 1: Customer (user) confirms an order, choose to pay on delivery.
• Step 2: Your system (partner system)) initiates an order containing order information associated with a unique orderId, then sends to MoMo for requesting the QRCode with the amount and order information.
• Step 3: MoMo generates the QR code, then sends it back to partner system.
• Step 4: Partner receives the QR code, then relays to the sender. Sender prints this QR code and attachs it to the parcel.

Paying with MOD on delivery

• Step 5: Once the product reaches, user makes a payment by scanning the QR code on the parcel using MoMo app.
• Step 6: User confirms the payment on MoMo app's 'secured payment screen'.
• Step 7: MoMo processes the payment, then returns the payment transaction result to Partner, as well as displays the result to user on MoMo app.

In this circumstances, shipper has to carefully check the payment result on user's MoMo app to ensure that payment transaction is completed sucessfully.

Usecase 2: QR Code displayed on the shipper app

Before shipping

• Step 1: Customer (user) confirms an order, choose to pay on delivery.
• Step 2: Your system (partner system)) receives and confirms order, and then sends order information to shipper app.

Paying with MOD on delivery

• Step 3: Shipper meets customer and requests the relevant QR code by choosing MOD payment method on the shipper app.
• Step 4: Partner server initiates an order containing order information associated with a unique orderId, then sends it to MoMo for requesting the QRCode with the amount and order information.
• Step 5: After validating the partner authentication, MoMo responds with the QRCode.
• Step 6: Partner server receives QRCode and processes it, then returns it to shipper app.
• Step 7: The QRCode is displayed in shipper app. Shipper shows QRCode to customer.
• Step 8: User scans the QR code by using MoMo app.
• Step 9: User confirms the payment on MoMo app's 'secured payment screen'.
• Step 10: MoMo processes the payment, then returns the payment transaction result to partner, as well as displays the result to user on Momo app.
• Step 11: Partner server receives the response and processes it, then returns to shipper app.
• Step 12: The successful result is diplayed for shipper's acknowledgement. Order is completed.

API Configuration

HTTP Information

Initiate Payment Method

On the merchant's payment page, after customers choose to pay with MoMo e-wallet, merchant server needs to call MoMo's API onDelivery to get payment methods and then apply suitable ones to their platforms.

requestType: Identify the type of the request

HTTP Request

POST /v2/gateway/api/create

Attribute	Type	Required	Description
partnerCode	String		Integration information
partnerName	String		Partner name
storeId	String		Store ID
requestId	String(50)		Request ID, unique for each request, MoMo's partner uses the requestId field for idempotency control
amount	Long		Amount needs to be paid Min: 1.000 VND Max: 20.000.000 VND Currency: VND Data type: Long
orderId	String		Partner Transaction ID Regex: ^[0-9a-zA-Z]([-_.]*[0-9a-zA-Z]+)*$
orderInfo	String		Order's information
redirectUrl	String		A partner's URL. This URL is used to redirect from MoMo page to partner's page after customer's payment. Support: AppLink and WebLink
ipnUrl	String		Partner API. Used by MoMo to submit payment results by IPN method (server-to-server) method
requestType	String		onDelivery
extraData	String		Default value is empty "" Encode base64 follow Jsonformat: {"key": "value"} Example with data: {"username": "momo"}=> data of extraData: eyJ1c2VybmFtZSI6ICJtb21vIn0=
autoCapture	Boolean		If set to false, the payment will not be automatically captured.
lang	String		Language of returned message (vi or en)
signature	String		Signature to confirm information. Secure transaction in Hmac_SHA256 with format: a String sort all key name of data field from a-z: accessKey=$accessKey&amount=$amount&extraData=$extraData &ipnUrl=$ipnUrl&orderId=$orderId&orderInfo=$orderInfo &partnerCode=$partnerCode&redirectUrl=$redirectUrl &requestId=$requestId&requestType=$requestType

Redirecting information (redirectUrl)

WebLink: Links to open website.

AppLink: Link to open mobile application.

Learn more about AppLink

• Android: https://developer.android.com/training/app-links
• IOS: https://developer.apple.com/documentation/uikit/core_app/..

Example Request

{
  "partnerCode": "MOMO",
  "partnerName" : "Test",
  "storeId" : "MoMoTestStore",
  "requestType": "onDelivery",
  "ipnUrl": "https://momo.vn",
  "redirectUrl": "https://momo.vn",
  "orderId": "MM1540456472575",
  "amount": 150000,
  "lang":  "vi",
  "orderInfo": "SDK team.",
  "requestId": "MM1540456472575",
  "extraData": "eyJ1c2VybmFtZSI6ICJtb21vIn0=",
  "signature": "fd37abbee777e13eaa0d0690d184e4d7e2fb43977281ab0e20701721f07a0e07"
}

HTTP Response

List of payment methods that MoMo provides:

Attribute	Type	Required	Description
partnerCode	String		Integration information
requestId	String		Same as the original request
orderId	String		Partner Transaction ID Regex: ^[0-9a-zA-Z]([-_.]*[0-9a-zA-Z]+)*$
amount	Long		Same as the original payment amount
responseTime	Long		Time to respond payment results to partner Format: timestamp
message	String		Error description, error language is based on lang
resultCode	int		Result Code
payUrl	String		URL for switching from the partner's page to the MoMo payment page
deeplink	String		URL to open MoMo application directly (Customers must install MoMo app first) and payment confirmation screen.
qrCodeUrl	String		Data to generate QR code if you want customers to scan the QR code directly on your purchase page or to print it on the invoice. Since the QR code is displayed on Driver app, this URL should be an URL intended for Driver / Shipper, and not Customer Note: This URL is NOT containing the image of the QR code, you need to use an external library to generate the QR code.
deeplinkMiniApp	String		URL to open the MoMo app's payment confirmation screen. Apply when partner's website is embedded into MoMo app.

On the production environment: You need to request permission to use qrCodeUrl, deeplink,deeplinkMiniApp fields.

Example response

{
  "partnerCode": "MOMO",
  "requestId": "MM1540456472575",
  "orderId": "MM1540456472575",
  "amount": 150000,
  "responseTime": 145256987,
  "message": "Thành công",
  "resultCode": 0,
  "payUrl": "https://test-payment.momo.vn/v2/gateway/pay?t=TU9NT1NKSTEyMDE5MDgyM3wxNjEzNTMyMDk3OTIyOjAxMjM0NTY3Nzg=",
  "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%3DcaptureWallet%26payType%3Dapp-in-app&appScheme=",
  "qrCodeUrl": "https://test-payment.momo.vn/gw_payment/s/zoVKZd"
}

Payment

You need to install MoMo Test app and use MoMo TEST Account to process payment.

Payment guideline: Login > Home screen > Scan QR.

Processing payment result

For more information, see Payment Notification.

Once the transaction is completed, MoMo's payment page will redirect back to the partner's page based on the redirectUrl field that you have put in the onDelivery command, and will attach additional parameters to the URL in the following format. Please note that this redirection happens within the Driver / Shipper app

Parameter description

Description for parameters which are used by MoMo in the URL redirectUrl and the body content of ipnUrl.

Attribute	Type	Required	Description
partnerCode	String		Integration Information
orderId	String		Partner Transaction ID Regex: ^[0-9a-zA-Z]([-_.]*[0-9a-zA-Z]+)*$
requestId	String		Partner's requestId
amount	Long		Payment amount
partnerUserId	String		MoMo's unique identifier for each MoMo eWallet account.
orderInfo	String		Order's information
orderType	String		momo_wallet
transId	Long		MoMo's transaction ID
resultCode	Integer		Transaction status of the order Result Code
message	String		Error description, languague is based on lang
payType	String		Payment type: web or qr
responseTime	Long		Time to respond payment results to partner Format: timestamp
extraData	String		Extra Data. Default: ""
signature	String		Signature to confirm information. Secure transaction in Hmac_SHA256  algorithm with format: a String sort all key name of data field from a-z: accessKey=$accessKey&amount=$amount&extraData=$extraData &message=$message&orderId=$orderId&orderInfo=$orderInfo &orderType=$orderType&partnerCode=$partnerCode&payType= $payType&requestId=$requestId&responseTime= $responseTime&resultCode=$resultCode&transId=$transId

See also

• Check Transaction Status
• Reverse & Refund
• Confirm Payment