Refund a Payment

Use this endpoint to request a full refund or partial refund of a successful ShopeePay transaction.

Types of Refund:

Full Refund: a transaction’s full amount
Partial Refund: multiple (partial) amounts as long as the sum does not exceed the transaction's full amount. Merchant should wait for the previous partial refund to complete successfully before creating the next partial refund.

The refund expiration period is set at 365 days, starting from when the initial payment is made.

Calling Create Refund endpoint will return 2 status types:

Success - transaction successfully refunded, customer can try paying again.
Failed - transaction can be found but it does not meet the requirements for refund.

Note: Refund endpoint supports idempotent response. Multiple API requests using the same payload will only trigger the action once to prevent the risk of creating duplicate refunds.

For detailed information about our refund eligibility criteria, please refer to this link

Specification

The following table is the specification of the API:

	MPM	CPM	Checkout with ShopeePay Link & Pay, Subscription	Authorization & Capture
HTTP Method	POST	POST	POST	POST
Service Code	78	80	58	69
Path	.../v1.0.2/qr/qr-mpm-refund	.../v1.0/qr/qr-cpm-refund	.../v1.0/debit/refund	.../v1.0/auth/refund
Version	v1.0.2	v1.0	v1.0	v1.0

Request Parameter

Field	Type	Mandatory	Description
originalPartnerReferenceNo	String	M	Unique identifier of the transaction that merchant would like to refund.
partnerRefundNo	String	M	Unique identifier of refund transaction generated by merchant. Accepts up to 64 characters.
merchantId	String	M	Unique identifier of merchant in merchant system.
externalStoreId	String	M	Unique identifier of store in merchant system.
refundAmount	Object	M
value	String	M	Refund amount, including cents. Sample: 10.000,00 will be placed with 10000.00
currency	String	M	Currency that is associated with the refund amount Accepted values: IDR
additionalInfo	Object	M
transactionType	uint32	M	Refer to Transaction Types for specific transaction types. Eligible transaction types for refund are: Payment Payment captured

Sample API Request

REQUEST

{
   "originalPartnerReferenceNo": "Testing-123",
   "partnerRefundNo": "Refund-Testing-123",
   "merchantId": "Merchant123",
   "externalStoreId": "Store123",
   "refundAmount": {
      "value": "10000.00",
      "currency": "IDR"
   },
   "additionalInfo": {
      "transactionType": 13
   }
}

Copy

Response Parameter

Field	Type	Mandatory	Description
responseCode	String	M	Error code to specify the error returned
responseMessage	String	M	Debug message to provide more information
partnerRefundNo	String	O	Unique identifier of refund transaction generated by merchant.
refundAmount	Object	O
value	String	C	Refund amount, including cents
currency	String	C	Currency that is associated with the refund amount. Accepted values: IDR
refundTime	String	M	Update time of the individual transaction. Using ISO-8601 timestamp format.
additionalInfo	Object	O
createTime	String	O	Create time of the individual transaction. Using ISO-8601 timestamp format.
transactionType	uint32	O	15, referring to refund transaction type. Refer to Transaction Types for specific Transaction Types
latestTransactionStatus	String	O	Refer to Transaction Status for specific transaction statuses
merchantId	String	O	Unique identifier of merchant in merchant system.
externalStoreId	String	O	Unique identifier of store in merchant system.
userIdHash	String	O	Used to identify the unique user.
terminalId	String	O	If terminal ID info exists in transaction.
paymentChannel	int32	O	Indicates the source of fund used. Refer to Payment Channels for the respective source of fund.

Additional Fields

API	Field	Type	Mandatory	Description
MPM CPM Checkout with ShopeePay Link & Pay Subscription	refundNo	String	M	Transaction serial number of the refund transaction in ShopeePay system.
Authorization & Capture	originalReferenceNo	String	C	Transaction identifier in ShopeePay system. Will be returned upon successful refund.

Sample API Response

Sample API Response MPM

RESPONSE

{
   "responseCode": "2007800",
   "responseMessage": "Successful",
   "refundNo": "Refund-Payment-123",
   "partnerRefundNo": "Refund-Testing-123",
   "refundAmount": {
      "value": "10000.00",
      "currency": "IDR"
   },
   "refundTime": "2022-07-20T07:30:00+07:00",
   "additionalInfo": {
      "createTime": "2022-07-20T07:30:00+07:00",
      "transactionType": 15,
      "merchantId": "Merchant123",
      "terminalId": "2903",
      "externalStoreId": "Store123",
      "userIdHash": "15e455125fba426a4a2bb9145b3af2906813a7f222f6eab93b026ead62dc8d76",
      "latestTransactionStatus": "00",
      "paymentChannel": 1
   }
}

Copy

Sample API Response CPM

RESPONSE

{
   "responseCode": "2008000",
   "responseMessage": "Successful",
   "refundNo": "Refund-Payment-123",
   "partnerRefundNo": "Refund-Testing-123",
   "refundAmount": {
      "value": "10000.00",
      "currency": "IDR"
   },
   "refundTime": "2022-07-20T07:30:00+07:00",
   "additionalInfo": {
      "createTime": "2022-07-20T07:30:00+07:00",
      "transactionType": 15,
      "merchantId": "Merchant123",
      "terminalId": "2903",
      "externalStoreId": "Store123",
      "userIdHash": "15e455125fba426a4a2bb9145b3af2906813a7f222f6eab93b026ead62dc8d76",
      "latestTransactionStatus": "00",
      "paymentChannel": 1
   }
}

Copy

Sample API Response Checkout with ShopeePay, Link&Pay, Subscription

RESPONSE

{
   "responseCode": "2005800",
   "responseMessage": "Successful",
   "refundNo": "Refund-Payment-123",
   "partnerRefundNo": "Refund-Testing-123",
   "refundAmount": {
      "value": "10000.00",
      "currency": "IDR"
   },
   "refundTime": "2022-07-20T07:30:00+07:00",
   "additionalInfo": {
      "createTime": "2022-07-20T07:30:00+07:00",
      "transactionType": 15,
      "merchantId": "Merchant123",
      "terminalId": "2903",
      "externalStoreId": "Store123",
      "userIdHash": "15e455125fba426a4a2bb9145b3af2906813a7f222f6eab93b026ead62dc8d76",
      "latestTransactionStatus": "00",
      "paymentChannel": 1
   }
}

Copy

Sample API Response for Authorization and Capture

RESPONSE

{
   "responseCode": "2006900",
   "responseMessage": "Successful",
   "refundNo": "143899353717011270",
   "partnerRefundNo": "partner_refund_no_integration_00010",
   "refundAmount": {
      "value": "1.00",
      "currency": "IDR"
   },
   "refundTime": "2024-05-01T18:00:10+07:00",
   "additionalInfo": {
      "createTime": "2024-05-01T18:00:09+07:00",
      "transactionType": 15,
      "merchantId": "merchant_123",
      "externalStoreId": "store_123",
      "userIdHash": "a8fbf03545686dacbe22beee16512f89d8403ce5a02d42512522724c1b09cfe1",
      "latestTransactionStatus": "00",
      "paymentChannel": 1
   },
   "originalReferenceNo": "143899353717011270"
}

Copy

Response Codes

Response Codes for MPM Payment

HTTP code	Service Code	Sub-error Code	Response Code	Response Message	Partner Action
200	78	00	2007800	Successful	Mark MPM refund process to corresponding status according to response.additionalInfo.latestTransactionStatus. Retry request "Check MPM Refund Status" periodically if didn't get final status
400	78	00	4007800	Bad Request	Mark MPM refund process to Failed. Retry request with proper parameter
400	78	01	4007801	Invalid field format {fieldName} Invalid field format {currency} Invalid Field Format	Mark MPM refund process to Failed. Retry request with proper parameter
400	78	02	4007802	Invalid mandatory field {fieldName} Invalid mandatory field {transactionType} Invalid mandatory field {merchantId} Invalid mandatory field {externalStoreId} Invalid mandatory field {merchantId}. Exceed maximum character length Invalid mandatory field {externalStoreId}. Exceed maximum character length Invalid mandatory field {originalPartnerReferenceNo} Invalid mandatory field {partnerRefundNo} Invalid mandatory field {partnerRefundNo}. Exceed Maximum 64 Characters. Invalid Mandatory Field + {error message}	Mark MPM refund process to Failed. Retry request with proper parameter
401	78	00	4017800	Unauthorized.{error message}	Mark MPM refund process to Failed. Retry request with proper parameter
401	78	01	4017801	Invalid Token	Mark MPM refund process to Failed. Retry request with proper parameter
403	78	00	4037800	Transaction Expired	Mark MPM refund process to Failed. Consult to Shopeepay about refund validity days
403	78	01	4037801	Feature not allowed	Mark MPM refund process to Failed. Contact Shopeepay to check merchant/store supported product flow
403	78	06	4037806	Feature Not Allowed. Service Is Temporarily Down For Scheduled Maintenance	Mark MPM refund process to Failed. Retry request periodically or consult to Shopeepay
403	78	14	4037814	Insufficient Funds	Mark MPM refund process to Failed. Check source of fund
403	78	15	4037815	Transaction not permitted. An ongoing refund for this payment exists Transaction not permitted. Mismatch Merchant/Store Transaction not permitted. Original transaction not successful Transaction not permitted. Request to refund does not meet rules Transaction not permitted. Cannot refund payment with voucher Transaction not permitted. Credit wallet balance exceeded	Mark MPM refund process to Failed. Retry request with proper parameter or consult to Shopeepay
404	78	01	4047801	Transaction not found	Mark MPM refund process to Failed. Retry request with proper parameter
404	78	08	4047808	Invalid merchant. Status Is Not Active Invalid {fieldName} Invalid Store. Status Is Not Active	Mark MPM refund process to Failed. Contact Shopeepay to check merchant/store status
404	78	13	4047813	Invalid amount. Mismatch refund amount Invalid amount. Non-positive amount is not allowed Invalid amount. Refund amount exceed transaction Invalid amount	Mark MPM refund process to Failed. Retry request with proper parameter
404	78	15	4047815	Transaction not permitted	Mark MPM refund process to Failed. Retry request periodically or consult to Shopeepay
404	78	18	4047818	Inconsistent Request	Mark MPM refund process to Failed. Retry request with proper parameter
405	78	01	4057801	Requested Operation Is Not Allowed	Mark MPM refund process to Failed. Retry request with proper parameter
409	78	00	4097800	Conflict	Mark MPM refund process to Pending. Retry request periodically or consult to Shopeepay
500	78	00	5007800	General Error	Mark MPM refund process to Pending. Retry request periodically or consult to Shopeepay
500	78	01	5007801	Internal Server Error	Mark MPM refund process to Pending. Retry request periodically or consult to Shopeepay
504	78	00	5047800	Timeout	Mark MPM refund process to Pending. Retry request periodically or consult to Shopeepay

Response Codes for CPM Payment

HTTP code	Service Code	Sub-error Code	Response Code	Response Message	Partner Action
200	80	00	2008000	Successful	Mark CPM refund process to corresponding status according to response.additionalInfo.latestTransactionStatus. Retry request "Check CPM Refund Status" periodically if didn't get final status
400	80	00	4008000	Bad Request	Mark CPM refund process to Failed. Retry request with proper parameter
400	80	01	4008001	Invalid field format {fieldName} Invalid field format {currency} Invalid Field Format	Mark CPM refund process to Failed. Retry request with proper parameter
400	80	02	4008002	Invalid mandatory field {fieldName} Invalid mandatory field {transactionType} Invalid mandatory field {merchantId} Invalid mandatory field {externalStoreId} Invalid mandatory field {merchantId}. Exceed maximum character length Invalid mandatory field {externalStoreId}. Exceed maximum character length Invalid mandatory field {originalPartnerReferenceNo} Invalid mandatory field {partnerRefundNo} Invalid mandatory field {partnerRefundNo}. Exceed Maximum 64 Characters. Invalid Mandatory Field + {error message}	Mark CPM refund process to Failed. Retry request with proper parameter
401	80	00	4018000	Unauthorized.{error message}	Mark CPM refund process to Failed. Retry request with proper parameter
401	80	01	4018001	Invalid Token	Mark CPM refund process to Failed. Retry request with proper parameter
403	80	00	4038000	Transaction Expired	Mark CPM refund process to Failed. Consult to Shopeepay about refund validity days
403	80	01	4038001	Feature not allowed	Mark CPM refund process to Failed. Contact Shopeepay to check merchant/store supported product flow
403	80	06	4038006	Feature Not Allowed. Service Is Temporarily Down For Scheduled Maintenance	Mark CPM refund process to Failed. Retry request periodically or consult to Shopeepay
403	80	14	4038014	Insufficient Funds	Mark CPM refund process to Failed. Retry request periodically or consult to Shopeepay
403	80	15	4038015	Transaction not permitted. An ongoing refund for this payment exists Transaction not permitted. Mismatch Merchant/Store Transaction not permitted. Original transaction not successful Transaction not permitted. Request to refund does not meet rules Transaction not permitted. Cannot refund payment with voucher Transaction not permitted. Credit wallet balance exceeded	Mark CPM refund process to Failed. Retry request with proper parameter or consult to Shopeepay
404	80	01	4048001	Transaction not found	Mark CPM refund process to Failed. Retry request with proper parameter
404	80	08	4048008	Invalid merchant. Status Is Not Active Invalid {fieldName} Invalid Store. Status Is Not Active	Mark CPM refund process to Failed. Contact Shopeepay to check merchant/store status
404	80	13	4048013	Invalid amount. Mismatch refund amount Invalid amount. Non-positive amount is not allowed Invalid amount. Refund amount exceed transaction Invalid amount	Mark CPM refund process to Failed. Retry request with proper parameter
404	80	15	4048015	Transaction not permitted	Mark CPM refund process to Failed. Retry request periodically or consult to Shopeepay
404	80	18	4048018	Inconsistent Request	Mark CPM refund process to Failed. Retry request with proper parameter
405	80	01	4058001	Requested Operation Is Not Allowed	Mark CPM refund process to Failed. Retry request with proper parameter
409	80	00	4098000	Conflict	Mark CPM refund process to Pending. Retry request periodically or request "Check CPM Refund Status" periodically to get final status
500	80	00	5008000	General Error	Mark CPM refund process to Pending. Retry request periodically or request "Check CPM Refund Status" periodically to get final status
500	80	01	5008001	Internal Server Error	Mark CPM refund process to Pending. Retry request periodically or request "Check CPM Refund Status" periodically to get final status
504	80	00	5048000	Timeout	Mark CPM refund process to Pending. Retry request periodically or request "Check CPM Refund Status" periodically to get final status

Response Codes for Checkout with ShopeePay, Link & Pay, Subscription

Response Codes for Checkout With ShopeePay

HTTP code	Service Code	Sub-error Code	Response Code	Response Message	Partner Action
200	58	00	2005800	Successful	Mark Debit refund process to corresponding status according to response.additionalInfo.latestTransactionStatus. Retry request "Check Debit Refund Status" periodically if didn't get final status
400	58	00	4005800	Bad Request	Mark Debit refund process to Failed. Retry request with proper parameter
400	58	01	4005801	Invalid field format {fieldName} Invalid field format {currency} Invalid Field Format	Mark Debit refund process to Failed. Retry request with proper parameter
400	58	02	4005802	Invalid mandatory field {fieldName} Invalid mandatory field {transactionType} Invalid mandatory field {merchantId} Invalid mandatory field {externalStoreId} Invalid mandatory field {merchantId}. Exceed maximum character length Invalid mandatory field {externalStoreId}. Exceed maximum character length Invalid mandatory field {originalPartnerReferenceNo} Invalid mandatory field {partnerRefundNo} Invalid mandatory field {partnerRefundNo}. Exceed Maximum 64 Characters. Invalid Mandatory Field + {error message}	Mark Debit refund process to Failed. Retry request with proper parameter
401	58	00	4015800	Unauthorized.{error message}	Mark Debit refund process to Failed. Retry request with proper parameter
401	58	01	4015801	Invalid Token	Mark Debit refund process to Failed. Retry request with proper parameter
403	58	00	4035800	Transaction Expired	Mark Debit refund process to Failed. Consult to Shopeepay about refund validity days
403	58	01	4035801	Feature not allowed	Mark Debit refund process to Failed. Contact Shopeepay to check merchant/store supported product flow
403	58	06	4035806	Feature Not Allowed. Service Is Temporarily Down For Scheduled Maintenance	Mark Debit refund process to Failed. Retry request periodically or consult to Shopeepay
403	58	14	4035814	Insufficient Funds	Mark Debit refund process to Failed. Check source of fund
403	58	15	4035815	Transaction not permitted. An ongoing refund for this payment exists Transaction not permitted. Mismatch Merchant/Store Transaction not permitted. Original transaction not successful Transaction not permitted. Request to refund does not meet rules Transaction not permitted. Cannot refund payment with voucher Transaction not permitted. Credit wallet balance exceeded	Mark Debit refund process to Failed. Retry request with proper parameter or consult to Shopeepay
404	58	01	4045801	Transaction not found	Mark Debit refund process to Failed. Retry request with proper parameter
404	58	08	4045808	Invalid merchant. Status Is Not Active Invalid {fieldName} Invalid Store. Status Is Not Active	Mark Debit refund process to Failed. Contact Shopeepay to check merchant/store status
404	58	13	4045813	Invalid amount. Mismatch refund amount Invalid amount. Non-positive amount is not allowed Invalid amount. Refund amount exceed transaction Invalid amount	Mark Debit refund process to Failed. Retry request with proper parameter
404	58	15	4045815	Transaction not permitted	Mark Debit refund process to Failed. Retry request periodically or consult to Shopeepay
404	58	18	4045818	Inconsistent Request	Mark Debit refund process to Failed. Retry request with proper parameter
405	58	01	4055801	Requested Operation Is Not Allowed	Mark Debit refund process to Failed. Retry request with proper parameter
409	58	00	4095800	Conflict	Mark Debit refund process to Pending. Retry request periodically or request "Check Debit Refund Status" periodically to get final status
500	58	00	5005800	General Error	Mark Debit refund process to Pending. Retry request periodically or request "Check Debit Refund Status" periodically to get final status
500	58	01	5005801	Internal Server Error	Mark Debit refund process to Pending. Retry request periodically or request "Check Debit Refund Status" periodically to get final status
504	58	00	5045800	Timeout	Mark Debit refund process to Pending. Retry request periodically or request "Check Debit Refund Status" periodically to get final status

Response Codes for Auth & Capture

HTTP code	Service Code	Sub-error Code	Response Code	Response Message	Partner Action
200	69	00	2006900	Successful	Mark Auth refund process to corresponding status according to response.additionalInfo.latestTransactionStatus. Retry request "Check Auth Refund Status" periodically if didn't get final status
400	69	00	4006900	Bad Request	Mark Auth refund process to Failed. Retry request with proper parameter
400	69	01	4006901	Invalid field format {fieldName} Invalid field format {currency} Invalid Field Format	Mark Auth refund process to Failed. Retry request with proper parameter
400	69	02	4006902	Invalid mandatory field {fieldName} Invalid mandatory field {transactionType} Invalid mandatory field {merchantId} Invalid mandatory field {externalStoreId} Invalid mandatory field {merchantId}. Exceed maximum character length Invalid mandatory field {externalStoreId}. Exceed maximum character length Invalid mandatory field {originalPartnerReferenceNo} Invalid mandatory field {partnerRefundNo} Invalid mandatory field {partnerRefundNo}. Exceed Maximum 64 Characters. Invalid Mandatory Field + {error message}	Mark Auth refund process to Failed. Retry request with proper parameter
401	69	00	4016900	Unauthorized.{error message}	Mark Auth refund process to Failed. Retry request with proper parameter
401	69	01	4016901	Invalid Token	Mark Auth refund process to Failed. Retry request with proper parameter
403	69	00	4036900	Transaction Expired	Mark Auth refund process to Failed. Consult to Shopeepay about refund validity days
403	69	01	4036901	Feature not allowed	Mark Auth refund process to Failed. Contact Shopeepay to check merchant/store supported product flow
403	69	06	4036906	Feature Not Allowed. Service Is Temporarily Down For Scheduled Maintenance	Mark Auth refund process to Failed. Retry request periodically or consult to Shopeepay
403	69	14	4036914	Insufficient Funds	Mark Auth refund process to Failed. Retry request periodically or consult to Shopeepay
403	69	15	4036915	Transaction not permitted. An ongoing refund for this payment exists Transaction not permitted. Mismatch Merchant/Store Transaction not permitted. Original transaction not successful Transaction not permitted. Request to refund does not meet rules Transaction not permitted. Cannot refund payment with voucher Transaction not permitted. Credit wallet balance exceeded	Mark Auth refund process to Failed. Retry request with proper parameter or consult to Shopeepay
404	69	01	4046901	Transaction not found	Mark Auth refund process to Failed. Retry request with proper parameter
404	69	08	4046908	Invalid merchant. Status Is Not Active Invalid fieldName Invalid Store. Status Is Not Active	Mark Auth refund process to Failed. Contact Shopeepay to check merchant/store status
404	69	13	4046913	Invalid amount. Mismatch refund amount Invalid amount. Non-positive amount is not allowed Invalid amount. Refund amount exceed transaction Invalid amount	Mark Auth refund process to Failed. Retry request with proper parameter or consult to Shopeepay
404	69	15	4046915	Transaction not permitted	Mark Auth refund process to Failed. Retry request with proper parameter
404	69	18	4046918	Inconsistent Request	Mark Auth refund process to Failed. Retry request with proper parameter
405	69	01	4056901	Requested Operation Is Not Allowed	Mark Auth refund process to Failed. Retry request with proper parameter
409	69	00	4096900	Conflict	Mark Auth refund process to Pending. Retry request periodically or request "Check Auth Refund Status" periodically to get final status
500	69	00	5006900	General Error	Mark Auth refund process to Pending. Retry request periodically or request "Check Auth Refund Status" periodically to get final status
500	69	01	5006901	Internal Server Error	Mark Auth refund process to Pending. Retry request periodically or request "Check Auth Refund Status" periodically to get final status
504	69	00	5046900	Timeout	Mark Auth refund process to Pending. Retry request periodically or request "Check Auth Refund Status" periodically to get final status

Refund a Payment

Refund a Payment

Specification

Request Parameter

Sample API Request

REQUEST

Response Parameter

Sample API Response

Sample API Response MPM

RESPONSE

Sample API Response CPM

RESPONSE

Sample API Response Checkout with ShopeePay, Link&Pay, Subscription

RESPONSE

Sample API Response for Authorization and Capture

RESPONSE

Response Codes

Response Codes for MPM Payment

Response Codes for CPM Payment

Response Codes for Checkout with ShopeePay, Link & Pay, Subscription

Response Codes for Checkout With ShopeePay

Response Codes for Auth & Capture

On this page