Refund API

Initiating refund for GoPay and GoPay Tokenization (non Pre-Auth) transaction

This section will describe how a merchant can initiate refunds for GoPay and GoPay Tokenization (non-Pre Auth) transactions.

Path	/{version}/debit/refund
HTTP Method	POST
Version	v1.0
SNAP Service Code	58

Request Header

Field Name	Field Type	Mandatory	Field Description
Content-type	String	M	Media type of the resource, i.e. application/json
X-TIMESTAMP	String	M	Client’s current local time in ISO-8601 format
X-SIGNATURE	String	M	Created using symmetric signature HMAC_SHA512 algorithm
Authorization	String	M	Represents access_token of a request; string starts with keyword “Bearer ” followed by access_token. Can get this token from Access Token B2B API response.
X-PARTNER-ID	String	M	Unique identifier for caller
X-EXTERNAL-ID	String	M	Alphanumeric string. We suggest merchant to use UUID format. The value should be unique. In case of timeout, merchant can do: Use this value in get status API to get status transaction or Retry this request with the same X-EXTERNAL-ID and request body to avoid creating duplicate transaction
CHANNEL-ID	String	M	Mandatory field from Bank Indonesia that can take any value with correct format 5 digits numeric string

Content-type:application/json
X-TIMESTAMP:2024-03-19T14:30:00+07:00
X-SIGNATURE: da1fa417c72d6b91c257e01e54fac824
Authorization: Bearer gp9HjjEj813Y9JGoqwOeOPWbnt4CupvIJbU1Mmu4a11MNDZ7Sg5u9a
X-PARTNER-ID: BMRI
X-EXTERNAL-ID:12345678901234567890
CHANNEL-ID:12345

Request Body

Field Name	Field Type	Mandatory	Field Description
originalExternalId	String (36)	C	If merchant got a timeout when calling charge API (POST /v1.0/debit/payment-host-to-host), merchant can pass the value of X-EXTERNAL-ID in the charge API request header as originalExternalId. Note: Either originalExternalId or OriginalReferenceNo need to be passed in refund request.
partnerRefundNo	String(64)	M	Unique identifier of refund transaction generated by merchant. If not passed then Midtrans creates a new one. It is recommended to use this parameter to avoid double refund attempts. Allowed characters are alphabets, numbers, dash (-), and underscore (_).
originalPartnerReferenceNo	String(64)	M	Transaction identifier on merchant side (merchant's order id).
originalReferenceNo	String(64)	C	Transaction identifier on service provider system. For e.g: GopayOrderId Note: Either originalExternalId or OriginalReferenceNo need to be passed. If both fields have value, will use originalReferenceNo as the main identifier.
refundAmount	Object	O	refundAmount object, if amount not set, system will treat as full refund request.
refundAmount.value	String (16,2)	O	Net amount of the refund. If it's IDR then the value includes 2 decimal digits. e.g. IDR 10.000 will be placed with 10000.00
refundAmount.currency	String (2)	O	Currency.
reason	String (256)	O	Reason for the refund. For Gopay transaction, this field will be shown on Gopay Order History
additionalInfo	Object	O	Additional Information
additionalInfo.paymentProviderMetadata	Object	O	Object containing the payment provider’s metadata parameter. This is used whenever merchant needs to pass additional information to payment provider.In the case of GoPay Later Multi Month, merchant needs to pass the required risk data information as agreed with GoPay Later team.

{
    "originalExternalId": "merchant-x-external-id",
    "originalPartnerReferenceNo":"merchant-order-id",
    "partnerRefundNo" : "merchant-refund-no",
    "originalReferenceNo" : "gopay-order-id",
     "refundAmount" : {
      "value":"10000.00",
      "currency":"IDR"
   },
   "reason" : "some-reason"
   "additionalInfo": {
   		"paymentProviderMetadata": {
      	"subOrders*": [
					"subOrderId*": string,
					"quantity*": int,
					"amount*": long
				]
      }
 	 }
}

Response Header

Field Name	Field Type	Mandatory	Field Description
Content-type	String	M	Media type of the resource, i.e. application/json
X-TIMESTAMP	String	M	Client’s current local time in ISO-8601 format

Content-type: application/json
X-TIMESTAMP: 2024-03-19T14:30:00+07:00

Response Body

Field Name	Field Type	Mandatory	Field Description
responseCode	String (7)	M	Response code
responseMessage	String (150)	M	Response description
originalReferenceNo	String (256)	M	Transaction identifier on service provider system. For e.g: GopayOrderId
refundNo	String(64)	M	Gopay refund number
partnerRefundNo	String(64)	M	Unique identifier of refund transaction generated by merchant. Merchant refund ID. If not passed then Midtrans creates a new one. It is recommended to use this parameter to avoid double refund attempts. Allowed characters are alphabets, numbers, dash (-), and underscore (_).
refundAmount	Object	O	refundAmount object
refundAmount.value	String (ISO 4217) (16,2)	O	Net amount of the refund. If it's IDR then the value includes 2 decimal digits. e.g. IDR 10.000,- will be placed with 10000.00
refundAmount.currency	String (2)	O	Currency.
refundTime	String(25)	M	Refund time. ISO 8601

{
   "responseCode":"20058000",
   "responseMessage":"Request has been processed successfully",
   "originalReferenceNo": "2020102977770000000009",
   "refundNo":"2020102900000000000001",
   "partnerRefundNo":"2020102900000000002323232",
   "refundAmount" : {
      "value":"10000.00",
      "currency":"IDR"
   },
   "refundTime" : "2023-07-03T10:36:17+07:00"
}

List of Response code

Response Code	HTTP Status Code	Response Message
2005800	200	Success
4005802	400	Invalid Mandatory Field
4015800	401	Unauthorized.
4015801	401	Invalid Token (B2B)
4035802	403	Exceeds Transaction Amount Limit
4035814	403	Insufficient Funds
4035815	403	Transaction Not Permitted.[reason].
4035823	403	Account Limit Exceed
4045801	404	Transaction Not Found
5005801	500	Internal Server Error
5045800	504	Timeout

Initiating refund for GoPay QRIS transaction

This section will describe how a merchant can initiate refunds for GoPay QRIS transactions.

Path	/{version}/qr/qr-mpm-refund
HTTP Method	POST
Version	v1.0
SNAP Service Code	78

Request Header

Field Name	Field Type	Mandatory	Field Description
Content-type	String	M	Media type of the resource, i.e. application/json
X-TIMESTAMP	String	M	Client’s current local time in ISO-8601 formatAirpay Shopee accepts refund only at 06:00 to 23:55 GMT+7
X-SIGNATURE	String	M	Created using symmetric signature HMAC_SHA512 algorithm
Authorization	String	M	Represents access_token of a request; string starts with keyword “Bearer ” followed by access_token. Can get this token from Access Token B2B response.
X-PARTNER-ID	String	M	Unique identifier for caller
X-EXTERNAL-ID	String	M	Alphanumeric string. We suggest merchant to use UUID format. The value should be unique. In case of timeout, merchant can do: Use this value in get status API to get status transaction or Retry this request with the same X-EXTERNAL-ID and request body to avoid creating duplicate transaction The value should also be the same as request_body.partnerRefundNo
CHANNEL-ID	String	M	Mandatory field from Bank Indonesia that can take any value with correct format 5 digits numeric string

Content-type:application/json
X-TIMESTAMP:2024-03-19T14:30:00+07:00
X-SIGNATURE:da1fa417c72d6b91c257e01e54fac824
Authorization:Bearer gp9HjjEj813Y9JGoqwOeOPWbnt4CupvIJbU1Mmu4a11MNDZ7Sg5u9a
X-PARTNER-ID:BMRI
X-EXTERNAL-ID:12345678901234567890
CHANNEL-ID:12345

Request Body

Field Name	Field Type	Mandatory	Field Description
merchantId	String (64)	M	Merchant identifier that is unique per each merchant.
subMerchantId	String(32)	O	Sub merchant ID
externalStoreId	String(64)	C	External store ID
originalPartnerReferenceNo	String(64)	M	Transaction identifier on service consumer system. For e.g : MerchantOrderId
originalReferenceNo	String(64)	O	Transaction identifier on service provider system. For e.g: GopayOrderId *either originalExternalId or OriginalReferenceNo need to be filled If both fields have value, will use originalReferenceNo as the main identifier.
originalExternalId	String(32)	O	Original customer reference number
partnerRefundNo	String(64)	M	ReferenceNumber from PJP AIS for the refund. This value should be filled with the same value as X-EXTERNAL-ID
refundAmount	Object	O	refundAmount object, if amount not set, system will treat as full refund request.
refundAmount.value	String (16,2)	O	Net amount of the refund. If it's IDR then the value includes 2 decimal digits. e.g. IDR 10.000,- will be placed with 10000.00. Airpay Shopee only supports full refund
refundAmount.currency	String (2)	O	Currency.
reason	String (256)	O	Reason for the refund.
additionalInfo	Object	O	Additional Information if merchant’s need to pass.

{
   "merchantId":"00007100010926",
   "subMerchantId":"310928924949487",
   "externalStoreId":"124928924949487",
   "originalPartnerReferenceNo":"2020102900000000000001",
   "originalReferenceNo":"2020102977770000000009",
   "originalExternalId":"10052019",
   "partnerRefundNo":"239850918204981205970",
   "refundAmount":{
      "value":"10000.00",
      "currency":"IDR"
   },
   "reason":"Customer complain",
   "additionalInfo":null
}

Response Header

Field Name	Field Type	Mandatory	Field Description
Content-type	String	M	Media type of the resource, i.e. application/json
X-TIMESTAMP	String	M	Client’s current local time in ISO-8601 format

Content-type:application/json
X-TIMESTAMP:2024-03-19T14:30:00+07:00

Response Body

Field Name	Field Type	Mandatory	Field Description
responseCode	String (7)	M	Response code
responseMessage	String(150)	M	Response description
originalPartnerReferenceNo	String(64)	O	Original transaction identifier on service consumer system
originalReferenceNo	String(64)	C	Original transaction identifier on service provider system
originalExternalId	String(32)	O	Original customer reference number
referenceNo	String(64)	M	referenceNumber
refundAmount	Object	O	refundAmount object
refundAmount.value	String (ISO 4217) (16,2)	O	Net amount of the refund. If it's IDR then the value includes 2 decimal digits. e.g. IDR 10.000,- will be placed with 10000.00
refundAmount.currency	String (2)	O	Currency.
partnerRefundNo	String(64)	M	Unique identifier of refund transaction generated by client. Merchant refund ID. If not passed then Midtrans creates a new one. It is recommended to use this parameter to avoid double refund attempts. Allowed characters are alphabets, numbers, dash (-), and underscore (_).
refundTime	String(25)	M	Refund time. ISO 8601
additionalInfo	Object	O	Additional Information if merchant’s need to pass.

{
   "responseCode":"2007800",
   "responseMessage":"Request has been processed successfully",
   "originalPartnerReferenceNo":"2020102900000000000001",
   "originalReferenceNo":"2020102977770000000009",
   "originalExternalId":"10052019",
   "referenceNo":"REF993883",
   "partnerRefundNo":"239850918204981205970",
   "refundAmount":{
      "value":"10000.00",
      "currency":"IDR"
   },
   "refundTime":"2020-12-21T17:21:41+07:00",
   "additionalInfo":null
}

List of Response code

Response Code	HTTP Status Code	Response Message
2007800	200	Success
4007802	400	Invalid Mandatory Field merchantId
4017800	401	Unauthorized. Signature
4017801	401	Invalid Token (B2B)
4037814	403	Insufficient Funds
4047800	404	Invalid Transaction Status
4047801	404	Transaction Not Found
4047813	404	Invalid amount or user balance exceeded.
4037802	403	Exceeds Transaction Amount Limit
4097801	409	Duplicate Transaction
4057801	405	Merchant refund request exceeds the allowed refund window.
5007801	500	Internal Server Error
5047800	504	Timeout

Initiating refund for GoPay Tokenization (Pre Auth) transaction

This section will describe how a merchant can initiate refunds for GoPay Tokenization (Pre Auth) transactions.

Path	/{version}/auth/refund
HTTP Method	POST
Version	v1.0
SNAP service code	69

Request Header

Field Name	Field Type	Mandatory	Field Description
Content-type	String	M	Media type of the resource, i.e. application/json
X-TIMESTAMP	String	M	Client’s current local time in ISO-8601 format
X-SIGNATURE	String	M	Created using symmetric signature HMAC_SHA512 algorithm
Authorization	String	M	Represents access_token of a request; string starts with keyword “Bearer ” followed by access_token. Can get this token from Access Token B2B API response.
X-PARTNER-ID	String	M	Unique identifier for caller (client_id)
X-EXTERNAL-ID	String	M	Alphanumeric string. We suggest merchant to use UUID format. The value should be unique. In case of timeout, merchant can do: Use this value in get status API to get status transaction or Retry this request with the same X-EXTERNAL-ID and request body to avoid creating duplicate transaction
CHANNEL-ID	String	M	Mandatory field from Bank Indonesia that can take any value with correct format 5 digits numeric string

Content-type:application/json
X-TIMESTAMP:2024-03-19T14:30:00+07:00
X-SIGNATURE: da1fa417c72d6b91c257e01e54fac824
Authorization: Bearer gp9HjjEj813Y9JGoqwOeOPWbnt4CupvIJbU1Mmu4a11MNDZ7Sg5u9a
X-PARTNER-ID: BMRI
X-EXTERNAL-ID:12345678901234567890
CHANNEL-ID:12345

Request Body

Field Name	Field Type	Mandatory	Field Description
originalReferenceNo	String(64)	C	Transaction identifier on service provider system. For e.g: GopayOrderId Note: either originalExternalId or OriginalReferenceNo need to be filled If both fields have value, will use originalReferenceNo as the main identifier.
originalPartnerReferenceNo	String (64)	M	Merchant order-id
partnerRefundNo	String(64)	M	ReferenceNumber from PJP AIS for the refund.
refundAmount	Object	O	Refund amount
refundAmount.value	String (ISO4217)	M	Net amount of the transaction. If it's IDR then value includes 2 decimal digits. e.g. IDR 10.000,- will be placed with 10000.00
refundAmount.currency	String(3)	M	Refund amount currency
reason	String(256)	O	Reason for the refund. For Gopay, this field will be shown on Gopay Order History
additionalInfo
additionalInfo.originalExternalId	String (36)	C	If merchant got a timeout from the auth endpoint, merchant can use this field using the X-EXTERNAL-ID value in the direct debit request header. Note: either originalExternalId or OriginalReferenceNo need to be filled

{
   "originalReferenceNo":"2020102900000000000001",
   "originalPartnerReferenceNo":"123123123123",
   "partnerRefundNo":"asdv-asdasdv-addasd-1231ewqqw-aaaa",
   "refundAmount":{
  	"value":"12345678.00",
  	"currency":"IDR"
   },
   "reason":"aReason",
   "additionalData":{
          "originalExternalId":"aId",
}
}

Response Header

Field Name	Field Type	Mandatory	Field Description
Content-type	String	M	Media type of the resource, i.e. application/json
X-TIMESTAMP	String	M	Client’s current local time in ISO-8601 format

Content-type: application/json
X-TIMESTAMP: 2024-03-19T14:30:00+07:00

Response Body

Field Name	Field Type	Mandatory	Field Description
responseCode	String (7)	M	Error code to specify the error returned.
responseMessage	String (150)	M	Debug message to provide more information.
originalReferenceNo	String (256)	O	Transaction identifier on service provider system. For e.g: GopayOrderId
partnerRefundNo	String (64)	O	PJSP's refund identifier. Used to trace the capture when there's any issue occurred.
refundNo	String (64)	M	Reference number
refundTime	String(25)	M	The time when the payment will be automatically expired. Using ISO 8601 format
refundAmount	Object	O	Refund amount
refundAmount.value	String (16,2)	O	Transaction amount that will be paid using this payment method If it's IDR then value includes 2 decimal digits. e.g. IDR 10.000,- will be placed with 10000.00
refundAmount.currency	String	O	Currency. For e.g: IDR

{
   "responseCode":"20054000",
   "responseMessage":"Request has been processed successfully",
    "originalReferenceNo":"2020102900000000000001",
   "refundNo":"asdv-asdasdv-addasd-1231ewqqw-aaaa",
    "partnerRefundNo":"refund0123",
   "refundTime":"2023-07-03T10:36:17+07:00",
   "refundAmount":{
  	"value":"12345678.00",
  	"currency":"IDR"
   }
}

{
   "responseCode":"4006901",
   "responseMessage":"There is some issue with the transaction request"
}

List of Response code

Response Code	HTTP Status Code	Response Message
2006900	200	Success
4006902	400	Invalid Mandatory Field {Field Name}
4016900	401	Unauthorized. Auth token required
4016901	401	Invalid Token (B2B)
4036902	403	Exceeds Transaction Amount Limit
4036914	403	Insufficient Funds
4036515	403	Transaction Not Permitted.[reason].
5006901	500	Internal Server Error
5046900	504	Timeout

Handling Order "Post-Process" in Refund Flow (Race-Condition)

When calling our Refund API, there might be a possibilities for you to encounter "error-"code":"2007" "cause":"Refund not processable when payment is in progress" , this scenario will happens if you make a call while the order "post-process" is still running. Our "post-process" is needed to ensure that any next action on behalf of that order (such as Refund) is secure. This "post-process" usually takes in a split micro-seconds.

In a condition where you have a use cases that needs you to initiate Refund right after the order settled, please implement a retry mechanism for calls that encountered with "error-"code":"2007". When you encounter this error, please set multiple layer of "backoff" mechanism where you

Retry the request after 1 second
Then if still encountered with this error, retry after 5 seconds, and so on

This approach ensures that your application interacts smoothly with our API once order processing is complete.