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. The same refund_id cannot be reused.
With Refund, refund request is made to Midtrans where Midtrans will then forward it to payment providers.
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 NoticeMerchant 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 |
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 ( | String | Optional |
amount | Amount to be refunded. By default whole transaction amount is refunded. | Long | Optional |
reason | Reason justifying the refund. 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",
"channel": "dragon",
"expiry_time":"2015-06-23 13:36:24",
"settlement_time":"2015-06-15 16:00:00"
}{
"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 are | 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 |
channel | The name of the payment channel provider. More details on request and possible values are available on Card Feature: Specific Channel. | String |
expiry_time | For regular card transactions (non-recurring, non-one-click, non-two-click token) and the 3DS redirect_url expires in 10 minutes. For authorized transaction expires in 8 days. | String |
settlement_time | Credit card settlement time refers to the duration it takes for a credit card transaction to be processed and transaction_status change to settlement. | String |
For notification JSON attributes, please follow the description on Get Status Response.