Refund transaction is called to reverse the money back to customers for transactions with payment status Settlement. If transaction's status is still Pending Authorize or Capture please use Cancel API instead.
We will use refund_key as the unique identifier from merchant. If you want to do retry the same refund request please use the same refund_key, but if you want to create a new refund request please use the new refund_key. If you don't sent us the refund_key we will treat it as a new request and generate the refund_key from our side.
Refund transaction is supported only for credit_card , gopay, shopeepay , QRIS , kredivo and akulaku payment methods.
With Refund, refund request is made to Midtrans where Midtrans will then forward it to payment providers.
For QRIS with acquirers AirPay (Shopee) and ShopeePay, the maximum refund window is 365 days.
For Kredivo, the maximum refund window is 14 days.
While the maximum refund window for GoPay is as stated below:
- QRIS ON-US (acquirers GoPay x issuer Gopay) : 45 days
- QRIS OFF-US (acquirers GoPay x issuer Other Player) : 7 days
- GoPay Tokenization : 180 days
- GoPay Deeplink : 45 days
- Other GoPay transactions: 180 days
Refund API can be used in both Core API and Snap integrations. If Refund capabilities is not available for you, please request for activation to Midtrans's support team.
Direct Refund Notice
Merchant can now just use 1 refund endpoint
/refundfor all refund usecases. Direct Refund endpoint however can still be used for existing merchants.
Refund Transaction Method
| HTTP Method | Endpoint | Definition |
|---|---|---|
| POST | BASE_URL/v2/{order_id OR transaction_id}/refund | Refund Transaction |
Refunding GoPay Static QRIS transaction
Starting January 2024, GoPay Static QRIS transaction can only be refunded by passing the Midtrans transaction ID (transaction_id) on the refund API call. Please ensure that your system can accommodate this change.
Refund Transaction Request
See sample on the right -- try it yourself!
{
"refund_key": "reference1",
"amount": 5000,
"reason": "for some reason"
}
| JSON Attribute | Description | Type | Required |
|---|---|---|---|
| refund_key | Merchant refund ID. If not passed then Midtrans creates a new one. It is recommended to use this parameter to avoid double refund attempt. Allowed characters are alphabets, numbers, dash (-), and underscore (_). | String | Optional |
| amount | Amount to be refunded. By default whole transaction amount is refunded. Note :Shopeepay does not support partial refund at the moment. | Long | Optional |
| reason | Reason justifying the refund. For GoPay & GoPay Tokenization payments, reason will be shown on customers' GoPay transaction history. Reason is mandatory for card payment with BNI as acquiring bank. If the value is not sent, Midtrans will autofill it with "refund request from merchant" to BNI. | String(255) | Optional |
Refund Transaction Response and Notification
Sample Response
{
"status_code": "200",
"status_message": "Success, refund request is approved",
"transaction_id": "447e846a-403e-47db-a5da-d7f3f06375d6",
"order_id": "vtcc05",
"payment_type": "credit_card",
"transaction_time": "2015-06-15 13:36:24",
"transaction_status": "refund",
"gross_amount": "10000.00",
"refund_chargeback_id": 1,
"refund_amount": "10000.00",
"refund_key": "reference1"
}
{
"status_code": "200",
"status_message": "Success, refund request is approved",
"transaction_id": "447e846a-403e-47db-a5da-d7f3f06375d6",
"order_id": "vtcc05",
"payment_type": "credit_card",
"transaction_time": "2015-06-15 13:36:24",
"transaction_status": "partial_refund",
"gross_amount": "10000.00",
"refund_chargeback_id": 1,
"refund_amount": "5000.00",
"refund_key": "reference1"
}
{
"status_code" : "412",
"status_message" : "Merchant cannot modify the status of the transaction"
}
{
"status_code" : "414",
"status_message" : "Refund request is rejected due to invalid amount"
}
{
"status_code" : "406",
"status_message" : "Duplicate refund ID"
}
{
"status_code" : "200",
"status_message" : "midtrans payment notification",
"transaction_id" : "249fc620-6017-4540-af7c-5a1c25788f46",
"masked_card" : "48111111-1114",
"order_id" : "example-1424936368",
"payment_type" : "credit_card",
"transaction_time" : "2021-02-26 14:39:33",
"transaction_status" : "partial_refund",
"fraud_status" : "accept",
"approval_code" : "1424936374393",
"signature_key" : "2802a264cb978fbc59f631c68d120cbda8dc853f5dfdc52301c615cf4f14e7a0b09aa...",
"bank" : "bni",
"gross_amount" : "30000.00",
"channel_response_code": "00",
"channel_response_message": "Approved",
"card_type": "credit",
"refund_amount": "12000.00",
"refunds": [
{
"refund_chargeback_id": 1,
"refund_amount": "5000.00",
"created_at": "2015-02-27 00:14:20",
"reason": "some reason",
"refund_key": "reference1",
"refund_method": "online"
},
{
"refund_chargeback_id": 2,
"refund_amount": "7000.00",
"created_at": "2015-02-28 01:23:15",
"reason": "",
"refund_key": "reference2",
"refund_method": "offline"
},
]
}
{
"status_code" : "200",
"status_message" : "midtrans payment notification",
"transaction_id" : "249fc620-6017-4540-af7c-5a1c25788f46",
"masked_card" : "48111111-1114",
"order_id" : "example-1424936368",
"payment_type" : "credit_card",
"transaction_time" : "2021-02-26 14:39:33",
"transaction_status" : "partial_refund",
"fraud_status" : "accept",
"approval_code" : "1424936374393",
"signature_key" : "2802a264cb978fbc59f631c68d120cbda8dc853f5dfdc52301c615cf4f14e7a0b09aa...",
"bank" : "bni",
"gross_amount" : "30000.00",
"channel_response_code": "00",
"channel_response_message": "Approved",
"card_type": "credit",
"refund_amount": "12000.00",
"refunds": [
{
"refund_chargeback_id": 1,
"refund_amount": "5000.00",
"created_at": "2015-02-27 00:14:20",
"reason": "some reason",
"refund_key": "reference1",
"refund_method": "online",
"bank_confirmed_at": "2015-02-27 02:30:20"
},
{
"refund_chargeback_id": 2,
"refund_amount": "7000.00",
"created_at": "2015-02-28 01:23:15",
"reason": "",
"refund_key": "reference2",
"refund_method": "offline",
"bank_confirmed_at": "2015-02-27 02:30:20"
},
]
}
| JSON Attribute | Description | Type |
|---|---|---|
| status_code | Status code of transaction charge result. | String |
| status_message | Description of transaction charge result. | String |
| transaction_id | Transaction ID given by Midtrans. | String |
| order_id | Order ID specified by you. | String |
| payment_type | The payment method used by the customer. | String |
| transaction_time | Timestamp of transaction in ISO 8601 format. Time Zone: GMT+7. | String |
| transaction_status | Transaction status after refund action. Possible values arerefund : Transaction is fully refunded. partial_refund: transaction is partially refunded. | String |
| gross_amount | Total amount of transaction in IDR. | String |
| refund_chargeback_id | Identification of the refund process. | String |
| refund_amount | Total amount to be refunded in IDR. | String |
| refund_key | Merchant refund reference key. | String |
For notification JSON attributes, please follow the description on Get Status Response.
Midtrans will return 2 refund post notifications to merchant - without and with bank_confirmed_at. We suggest for merchant to use the later refund post notification with bank_confirmed_at to mark the refund has been succesfully confirmed by the bank/payment providers.