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. Reference number that should be unique in the same day or 1 day idempotency key | |
| CHANNEL-ID | String | M | Channel ID Device identification on which the API services are currently being accessed by the end user. Given by BI | |
Content-type:application/json
X-TIMESTAMP:2020-01-01T00:00: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 (_). |
|
| 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 | |
{
"originalExternalId": "merchant-order-id",
"partnerRefundNo" : "merchant-refund-no",
"originalReferenceNo" : "gopay-order-id",
"refundAmount" : {
"value":"10000.00",
"currency":"IDR"
},
"reason" : "some-reason"
}
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: 2020-01-01T00:00: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) |
| 4035814 | 403 | Insufficient Funds |
| 4035815 | 403 | Transaction Not Permitted.[reason]. |
| 4095801 | 409 | Duplicate partnerReferenceNo |
| 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 | |
| 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 | Numeric string. Preferably UUID. Reference number that should be unique in the same day or 1 day idempotency key | |
| CHANNEL-ID | String | M | Channel id Device identification on which the API services are currently being accessed by the end
user. Given by BI |
|
Content-type:application/json
X-TIMESTAMP:2020-01-01T00:00: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) | O | If the merchant got a timeout from the direct debit endpoint, merchant can use this field using the X-EXTERNAL-ID value in the direct debit request header.
*either originalExternalId or OriginalReferenceNo need to be filled |
|
| 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. | |
| 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. | |
| 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:2020-01-01T00:00: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
}
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 | Numeric string. Preferably UUID. Reference number that should be unique in the same day or 1 day idempotency key | |
| CHANNEL-ID | String | M | Channel id Device identification on which the API services are currently being accessed by the end user. Given by BI | |
Content-type:application/json
X-TIMESTAMP:2020-01-01T00:00: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: 2020-01-01T00:00: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) |
| 4036914 | 403 | Insufficient Funds |
| 4036515 | 403 | Transaction Not Permitted.[reason]. |
| 4095801 | 409 | Duplicate partnerReferenceNo |
| 5006901 | 500 | Internal Server Error |
| 5046900 | 504 | Timeout |