Direct Refund Transaction

Unlike the Refund Transaction, Direct Refund transaction is triggered to send the refund request directly to the bank or to the third-party payment provider for transaction with payment status Settlement. If payment status is still in either Capture, Pending or Authorize, use the Cancel API instead. This method is faster than the standard operation process which may take one to two days, after the initial refund request. The status of corresponding transaction is updated immediately after receiving refund result from the third-party payment provider. HTTP notification is sent only if the refund is successful. Do note that some payment method only supports refunding via Refund API, and vice versa.

Direct Refund transaction is only supported for GoPay, QRIS, ShopeePay, Credit Card, Akulaku and Kredivo payment methods. Currently for Credit Card payment method, Midtrans only supports BCA, MAYBANK, BNI (via Cybersource) and BRI acquiring banks.

For QRIS with acquirers AirPay (Shopee) and ShopeePay, the maximum refund window is 24 hours since the transaction is paid. Refund is not allowed from 11:55 PM to 6:00 AM GMT+7. If you send Direct Refund during this timeframe, the request gets rejected by ShopeePay. For Kredivo, the maximum refund window is 14 days.

While the maximum refund window for GoPay is as stated below:

  • QRIS with acquirers GoPay: 45 days
  • GoPay Tokenization and GoPay deeplink with GoPay payment option GOPAY_COINS: 90 days
  • Other GoPay transactions: 180 days

Direct 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 Transaction Method


HTTP MethodEndpointDefinition
POSTBASE_URL/v2/{order_id **OR** transaction_id}/refund/online/directDirect Refund Transaction


Direct Refund Transaction Request


See sample on the right -- try it yourself!

{
  "refund_key": "reference1",
  "amount": 5000,
  "reason": "for some reason"
}
JSON AttributeDescriptionTypeRequired
refund_keyMerchant refund ID. If not passed then Midtrans creates a new refund ID. It is recommended to use this parameter to avoid double refund attempt.StringOptional
amountAmount to be refunded. By default whole transaction amount is refund.LongOptional
reasonReason justifying the refund.
For GoPay & GoPay Tokenization payments, reason will be shown on customers' GoPay transaction history.
String(255)Optional



Direct Refund Transaction Response and Notifications


Sample Response


{
  "status_code": "200",
  "status_message": "Success, refund request is approved by the bank",
  "transaction_id": "fddb5889-fd39-46fe-809d-30679fe42434",
  "order_id": "MID-1620622357",
  "gross_amount": "10000.00",
  "payment_type": "credit_card",
  "transaction_time": "2016-06-28 09:42:20",
  "transaction_status": "refund",
  "refund_chargeback_id": 47594,
  "refund_amount": "10000.00",
  "refund_key": "01f1f771-b75c-48ef-b21d-193a79f8aa5b"
}
{
  "status_code": "202",
  "status_message": "Refund denied by the bank",
  "transaction_id": "fddb5889-fd39-46fe-809d-30679fe42434",
  "order_id": "MID-1620622357",
  "gross_amount": "10000.00",
  "payment_type": "credit_card",
  "transaction_time": "2016-06-28 09:42:20",
  "transaction_status": "settlement",
  "refund_chargeback_id": 47594,
  "refund_amount": "0.00",
  "refund_key": "01f1f771-b75c-48ef-b21d-193a79f8aa5b"
}
{
  "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": "841c7da8-530b-435a-9f67-c9d632d15537",
  "order_id": "1000176721005355",
  "gross_amount": "698879.00",
  "payment_type": "credit_card",
  "transaction_time": "2015-02-04 00:53:55",
  "transaction_status": "refund",
  "signature_key": "f1066b06ec8a4b7d6ffb941fd9772f6df304618e15e02cf17c2914cec12793e19c71653042f7f617b027eae6ecb6759529c67eca9af55264b736408d8b4df2b9",
  "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": "841c7da8-530b-435a-9f67-c9d632d15537",
  "order_id": "1000176721005355",
  "gross_amount": "698879.00",
  "payment_type": "credit_card",
  "transaction_time": "2015-02-04 00:53:55",
  "transaction_status": "refund",
  "signature_key": "f1066b06ec8a4b7d6ffb941fd9772f6df304618e15e02cf17c2914cec12793e19c71653042f7f617b027eae6ecb6759529c67eca9af55264b736408d8b4df2b9",
  "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"
    },
  ]
}
{
  "status_code": "200",
  "status_message": "midtrans payment notification",
  "transaction_id": "841c7da8-530b-435a-9f67-c9d632d15537",
  "order_id": "1000176721005355",
  "gross_amount": "698879.00",
  "payment_type": "credit_card",
  "transaction_time": "2016-07-04 00:53:55",
  "transaction_status": "partial_refund",
  "signature_key": "f1066b06ec8a4b7d6ffb941fd9772f6df304618e15e02cf17c2914cec12793e19c71653042f7f617b027eae6ecb6759529c67eca9af55264b736408d8b4df2b9"
}
JSON AttributeDescriptionType
transaction_idTransaction ID given by Midtrans.String
order_idOrder ID specified by you.String
gross_amountTotal amount of transaction in IDR.String
payment_typeThe payment method used by the customer.String
transaction_timeTimestamp of transaction in ISO 8601 format. Time Zone: GMT+7.String
transaction_statusTransaction status after refund action. Possible values are
refund : Transaction is fully refunded.
partial_refund: transaction is partially refunded.
String
status_codeStatus code of transaction charge result.String
status_messageDescription of transaction charge result.String
refund_chargeback_idIdentification of the refund process.String
refund_amountCumulative amount refunded.String
refund_keyMerchant refund reference. Allowed characters are alphabets, numbers, dash (-), and underscore (_).String

📘

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.

Language
Authorization
Basic
base64
:
Click Try It! to start a request and see the response here!