Refund Transactions

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 ,ovo, QRIS , kredivo and akulaku payment methods.

With Refund, refund request is made to Midtrans where Midtrans will then forward it to payment providers.

Notes on the specific non-GoPay max refund window:

ShopeePay (QRIS and JumpApp) : 365 days
Kredivo : 14 days
OVO : refund must be done within the same day of transactions. Any refund requested after the day of transaction, even it happen less than 24 hour will be rejected.

🚧
OVO Refund Window Implementation Example
Allowed

Transaction time: 23 Jan 2018, 17:00

Refund request: 23 Jan 2018, 21:30

Not Allowed

Transaction time: 24 Feb 2019, 22:00

Refund request: 25 Feb 2019, 00:19

Max refund window for GoPay :

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 /refund for 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 (`_`). In the case where merchant needs to reattempt a refund with the same refund key, the reattempt can only be done max 7 days after the first refund attempt. After 7 days, the same refund key cannot be used anymore and merchant needs to use a new refund key to initiate a refund. Reattempt of refunds may be needed if the previous attempt failed due to a retriable error (e.g insufficient merchant balance).	String	Optional
amount	Amount to be refunded. By default whole transaction amount is refunded. Note : `Shopeepay` and `OVO` 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

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 (_).

In the case where merchant needs to reattempt a refund with the same refund key, the reattempt can only be done max 7 days after the first refund attempt. After 7 days, the same refund key cannot be used anymore and merchant needs to use a new refund key to initiate a refund.

Reattempt of refunds may be needed if the previous attempt failed due to a retriable error (e.g insufficient merchant balance).

String

Optional

amount

Amount to be refunded. By default whole transaction amount is refunded. Note :
Shopeepay and OVO 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",
  "payer_phone_number" : "081111111", // only applicable for OVO as payment method
  "merchant_invoice" : "INV20251112001" // only applicable for OVO as payment method
}

{
  "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
payer_phone_number	Customer's phone number that used to create payment request to payment provider.	String
merchant_invoice	Unique identifier for payment provider specific request.	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.