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.
|
|
| 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]. |
| 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 format
Airpay 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.
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 |
| 4037814 | 403 | Insufficient Funds |
| 4047800 | 404 | Invalid Transaction Status |
| 4047801 | 404 | Transaction Not Found |
| 4037802 | 403 | Exceeds Transaction Amount Limit |
| 4097801 | 409 | Duplicate Transaction |
| 4057801 | 405 | Requested Operation Is Not Allowed |
| 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.
|
|
| 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.