Refund Transactions

post https://api.sandbox.midtrans.com/v2/order_id/refund

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.

Refund transaction is supported only for credit_card payment method. Banks which support this method are BNI, Mandiri, and CIMB.

With Refund, refund request is made to Midtrans where Midtrans will then forward it to payment providers. Do note that some payment method only supports refunding via Direct Refund API and vice versa.

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.

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 (`-`), and underscore (`_`).	String	Optional
amount	Amount to be refunded. By default whole transaction amount is refunded.	Long	Optional
reason	Reason justifying the refund.	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 are `refund` : 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.