Non-hosted payments

To have complete control of the customer experience, non-hosted payment page will be applied to allow customers enter their payment information directly on your website. In this case, follow these APIs to make payments.

Process Flow

API Configuration

HTTP Information

Initiate transaction with non-hosted payment page

First, it is required to create a transaction request for non-hosted payments. Access Initiate Transaction to learn more.

Process Transaction

It is used to process the transaction with respect to requestType (payWithATM) provided by merchant in the request. We will return bank form for user to make authentication.

HTTP Request

POST /v2/gateway/api/pay

Header

Attribute	Type	Required	Description
mToken	String		The recieved mToken from Initiate API
partnerCode	String		Integration information
orderId	String		OrderId of partner, it must match with which has been initiated from Initiate API
requestId	String(50)		Request ID, unique for each request, MoMo's partner uses the requestId field for idempotency control

Body

Attribute	Type	Required	Description
cardInfo	Object		The cardholder's infomation
requestType	String		payWithATM
generateCardToken	Boolean		true or false. If set to true, callbackToken will be sent to merchant using the IPN and redirect mechanism after user completes the payment. Merchant could use this callbackToken to get the recurring token for specific user (partnerClient).
amount	Long		Amount needs to be paid Min: 10.000 VND Max: 50.000.000 VND Currency: VND Data type: Long Note: this field must match with which has been initiated in Initiate API
lang	String		Language of returned message (vi or en)

Details of cardInfo content

Attribute	Type	Required	Description
cardFullName	String		Full name displayed on the card
cardIssueDate	String		Date can be found on the card, written as MM/YY (month and year). Use Card issue date in case both Card issue date and Card expiration date are available
cardNumber	String		Card Number

Example cardInfo

{
    "cardFullName": "Nguyen Van A",
    "cardNumber":"0704 0000 0000 0018",
    "cardIssueDate":"03/07"
}

Example Request body

{
    "cardInfo":{
          "cardNumber":"0704 0000 0000 0018",
          "cardFullName":"NGUYEN VAN A",
          "cardIssueDate":"03/07",
    },
    "amount":100000,
    "requestType": "payWithATM",
    "generateCardToken": true,
    "lang":"en"
}

Try yourself

HTTP Response

Attribute	Type	Required	Description
partnerCode	String		Integration information
orderId	String		Partner Transaction ID
requestId	String		Same as the original request
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 to open authentication page

Example response

{
    "partnerCode": "MOMOIOLD20190129",
    "orderId": "1666005197362:0123456778",
    "requestId": "1666756292133id",
    "amount": 100000,
    "resultCode": 0,
    "message": "Thành công.",
    "responseTime": 1666005325735,
    "payUrl": "https://test-payment.momo.vn/service-napas-cashin-app-bank/napas/build_data_form?orderId=2735570207"
}

Processing payment result

For more information, see Payment Notification.

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
requestId	String		Each Request’s Identification
amount	Long		Amount to pay
orderId	String		OrderId of partner, unique for each request
orderType	String		momo_wallet
orderInfo	String		Order info
partnerUserId	String		MoMo's unique identifier for each MoMo eWallet account.
partnerClientId	String		Identifier of user. partnerClientId is required only when generateCardToken = true
callbackToken	String		Token info used to get payment token, received only when generateCardToken = true and partnerClientId has been provided
transId	Long		MoMo's transaction ID
resultCode	Integer		Order status
message	String		description of resultCode based on lang
payType	String		napas
responseTime	Long		Time to return payment result in miliseconds
extraData	String		Additional info
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&callbackToken= $callbackToken&extraData=$extraData&message=$message &orderId=$orderId&orderInfo=$orderInfo&orderType= $orderType&partnerClientId=$partnerClientId &partnerCode=$partnerCode&payType=$payType&requestId= $requestId&responseTime=$responseTime&resultCode= $resultCode&transId=$transId

In case generateCardToken is true, process with API Receive recurring token after this successful payment.

Result Codes & Messages

These result codes and messages are exclusively assigned for Non-hosted payments flow within the context of Local ATM Card Payments. Additionally, kindly locate other result codes and messages in the comprehensive list of result codes provided here.

Result code	Description	Final Status	Recommended actions	Type
0	Successful.	Yes
21	Request is rejected due to invalid transaction amount.	No	Make sure that the initiated amount in both Initate Transaction and Process Transaction is the same.	Merchant error
72	Card number is in bad format.	No	Validate that the card number entered from user must match with first 6 number from bankcodes and its length must in 16 - 19 number.	Merchant error
73	Cardholder's name is in bad format.	No	Validate that the cardholder's name entered by user must be in alphabet format.	Merchant error
74	Card issuance date is in bad format.	No	Validate that the issuance date entered by user must be in MM/YY format.	Merchant error
75	Card expired date is in bad format.	No	Validate that the expired date entered by user must be in MM/YY format.	Merchant error
1001	Transaction failed due to insufficient funds.	Yes	Notify user the insufficient funds issue and request them to use another card or top up this card.	User error
1002	Transaction rejected by the issuers of the payment accounts.	Yes	Please choose other payment methods.	User error
1004	Transaction value exceeds maximum limit set by bank.	Yes	Notify user the maximum limitation and request them to try with less payment or use another cards.	User error
1006	Transaction failed because user has denied to confirm the payment.	Yes	Please send another payment request.	User error
1007	Card is locked.	Yes	Notify user the locked card issue and request them to use another cards or payment methods.	User error
1702	Card number is invalid.	Yes	Please make sure the card number is correct.	User error
1703	Cardholder's name is incorrect.	Yes	Please make sure the cardholder's name is correct.	User error
1704	Card issuance date is incorrect.	Yes	Please make sure the card issuance date is correct.	User error
1705	Card expired date is incorrect.	Yes	Please make sure the card expired date is correct.	User error
1711	Card is expired	Yes	Please make sure the card is still available to use.	User error
1713	Card is restricted	Yes	Please make sure the card is unrestricted.	User error
2001	Transaction failed due to invalid token.	Yes	Make sure that the mToken has not been used before, while partnerCode and orderId is correct.	Merchant error
4010	OTP verification failed.	Yes	User authentication failed. Please request another authentication.	User error
7002	Transaction is being processed by the provider of the payment instrument selected.	Yes	Please wait for the transaction to be processed. The transaction status will be notified once it's done processing.	Pending

Pay using token

In case user would like to pay with a card saved before, call API Pay using token retrieved from Receive recurring token.

See also

• Get bank codes and logos
• Check Transaction Status
• Reverse & Refund
• Confirm Payment