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
HTTP Request
POST /v2/gateway/api/refund
Attribute | Type | Required | Description |
---|---|---|---|
partnerCode | String | Integration information | |
subPartnerCode | String | Sub partner Id | |
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 | |
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
}
]
}