Reverse & Refund

Use to refund a payment transaction.

Partial refund: Refund part of the transaction amount (when the amount to be refunded is less than the paid amount).

Full refund: Refund all of the transaction amount (when the amount to be refunded is equal to the paid amount).

Process Flow

API Configuration

Minimum timeout when call this API must be 30s to ensure receive response from MoMo.

HTTP Request

POST /v2/gateway/api/refund

Attribute	Type	Required	Description
partnerCode	String		Integration information
orderId	String		orderId (new) of the refund transaction which must be different from orderId of the original purchase transaction
requestId	String(50)		Request ID, unique for each request, MoMo's partner uses the requestId field for idempotency control
amount	Long		Amount to be refunded Min: 1.000 VND (10.000 VND for Local ATM Card payment method) Max: 50.000.000 VND (30.000.000 VND for Tokenization payment method) Currency: VND
transId	Long		MoMo's transaction ID. This ID is provided by MoMo when the purchase transaction is successful
lang	String		Language of returned message (vi or en)
description	String		Description of refund request
transGroup	JsonArray		List items for refund (Buy Now Pay Later)
signature	String		Signature to check information. Use Hmac_SHA256 algorithm with data in format: accessKey=$acessKey&amount=$amount&description= $description&orderId=$orderId&partnerCode=$partnerCode &requestId=$requestId&transId=$transId

Data of each transGroup

Attribute	Type	Required	Description
itemId	String		Id of item
amount	Long		Amount of item to be refunded
transId	Long		MoMo's transaction ID. Transaction Id of item

Example request

{
  "partnerCode": "MOMO",
  "orderId": "1527297954700",
  "requestId": "1527314064527",
  "amount": 350000,
  "transId": 144492817,
  "lang": "en",
  "description": "",
  "transGroup": [
    {
      "itemId": "1655435780SKU_1",
      "amount": "200000",
      "transId": "2824581984"
    },
    {
      "itemId": "1655435780SKU_2",
      "amount": "120000",
      "transId": "2824581983"
    },
    {
      "itemId": "shipmentFee",
      "amount": "30000",
      "transId": "2824581982"
    }
  ],
  "signature": "8cdba11a7ff4cc7267d2b23c1f5d228a2ee52af1095420f9571c2d64ec6735fe"
}

HTTP Response

Attribute	Type	Required	Description
partnerCode	String		Integration information
orderId	String		Partner Transaction ID Regex: ^[0-9a-zA-Z]([-_.]*[0-9a-zA-Z]+)*$
requestId	String		Unique ID of each request
amount	Long		Refunded Amount
transId	Long		MoMo's transaction ID
resultCode	int		Result Code
message	String		Error description based on lang
responseTime	Long		Time to respond payment results to partner Format: timestamp
transGroup	JsonArray		Refunded items (Buy Now Pay Later).

Data of each transGroup

Attribute	Type	Required	Description
itemId	String		Id of item
amount	Long		Refunded Amount
refundTransId	Long		MoMo's transaction ID
resultCode	int		Result Code
message	String		Error description based on lang

Example response

{
  "partnerCode": "MOMO",
  "orderId": "OD1672315832109",
  "requestId": "RE1672315832109",
  "amount": 350000,
  "transId": 2820086739,
  "resultCode": 0,
  "message": "Successful.",
  "responseTime": 1672315843986,
  "transGroup": [
    {
      "itemId": "1655435780SKU_1",
      "amount": 200000,
      "refundTransId": 2820086739,
      "resultCode": 0,
      "message": "Successful."
    },
    {
      "itemId": "1655435780SKU_2",
      "amount": 120000,
      "resultCode": 7002,
      "message": "Transaction is being processed by the provider of the payment instrument selected."
    },
    {
      "itemId": "shipmentFee",
      "amount": 300000,
      "refundTransId": 2820086740,
      "resultCode": 0,
      "message": "Successful."
    }
  ]
}

Query Refund Result

POST /v2/gateway/api/refund/query

HTTP Request

Attribute	Type	Required	Description
partnerCode	String		Integration information
requestId	String		Request’s Identification
orderId	String		OrderId of refund transaction
lang	String		Language of returned message (vi or en)
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&orderId=$orderId &partnerCode=$partnerCode&requestId=$requestId

HTTP Response

Attribute	Type	Required	Description
partnerCode	String		Integration information
orderId	String		Partner Transaction ID Regex: ^[0-9a-zA-Z]([-_.]*[0-9a-zA-Z]+)*$
requestId	String		Unique ID of each request
resultCode	int		Result Code
message	String		Error description based on lang
responseTime	Long		Time to respond payment results to partner Format: timestamp
refundTrans	List		List transaction refund
items	List		List items of transaction

Data of each refundTrans

Attribute	Type	Required	Description
orderId	String		Partner Transaction ID
amount	Long		Refunded amount
resultCode	int		Result Code
transId	Long		MoMo's transaction ID
createdTime	Long		Refund time Format: timestamp

Data of each items

Attribute	Type	Required	Description
id	String		The Id of item
resultCode	int		Result Code
resultDescription	String		Result Description
refundCount	String		Number of refunds
refundAmount	String		Total amount refunded

Example Request

{
    "partnerCode": "MOMO_PARTNER_A",
    "requestId": "RE1671443986775",
    "orderId": "OD1671439294036",
    "lang":  "en",
    "signature": "b9db0af61956a914f3b7ecd1ca626d097603601323c0925bb0494ce2fc39aa6b"
}

Example Response

{
    "partnerCode": "MOMO_PARTNER_A",
    "orderId": "1671179937393:0123456789",
    "requestId": "RE1671435190248",
    "resultCode": 0,
    "message": "Successful.",
    "responseTime": 1671435191197,
    "refundTrans": [
        {
            "orderId": "OD1671432799944",
            "amount": 102220,
            "resultCode": 0,
            "transId": 2816637972,
            "createdTime": 1671432958966
        },
        {
            "orderId": "OD1671432799945",
            "amount": 306660,
            "resultCode": 1002,
            "transId": 0,
            "createdTime": 1671433055505
        }
    ],
    "items": [
        {
            "id": "1671179937SKU_1",
            "resultCode": 0,
            "resultDescription": "Successful.",
            "refundCount": 1,
            "refundAmount": 102220
        },
        {
            "id": "1671179937SKU_2",
            "resultCode": 0,
            "resultDescription": "Successful.",
            "refundCount": 0,
            "refundAmount": 0
        }
    ]
}