Refund a Payment
Refund a Payment
Use this endpoint to request a full refund or partial refund of a successful ShopeePay transaction.
- URL: "/v3/merchant-host/transaction/refund/create-new"
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.
Request Parameters
| Field | Type | Mandatory | Description |
|---|---|---|---|
| request_id | string | Y | Unique identifier for request, accepts up to 64 characters. |
| reference_id | string | Y | Unique identifier of transaction generated by merchant, referring topayment_reference_id passed to ShopeePay when payment was created. |
| transaction_type | uint32 | Y | Refer to Transaction Types for specific transaction types.Eligible transaction types for refund are: all payment transaction type. |
| refund_reference_id | string | Y | Unique identifier of refund transaction generated by merchant.Accepts up to 64 characters. |
| merchant_ext_id | string | Y | Unique identifier of merchant in merchant system. |
| store_ext_id | string | Y | Unique identifier of store in merchant system. |
| amount | int64 | Y | Amount of the refund transaction, inflated by a factor of 100. A positive integer in the smallest currency unit, with no decimal point.Example:Smallest amount will be 1, which represents 0.01.For currencies that do not have denomination in cents, the smallest amount will be 100, which represents 1 IDR (Rp 1) or 1 VND (₫ 1).If merchant is on full refund and did not pass this parameter, the refund request will be processed as usual. |
Sample API Request
REQUEST
{"request_id": "input-refund-request-id-here","reference_id": "payment_abc12345","transaction_type": 13,"refund_reference_id": "unique-refund-ref-id","merchant_ext_id": "external-merchant","store_ext_id": "external-store","amount": 10000}
Copy
Response Parameters
| Field | Type | Description |
|---|---|---|
| request_id | string | Unique identifier for request. |
| errcode | int32 | Error code to specify the error returned. |
| debug_msg | string | Debug message to provide more information. |
| transaction | object | Will return empty list if no such transaction. |
| * reference_id | string | Unique identifier of refund transaction generated by merchant. |
| * amount | int64 | Amount of the refund transaction, inflated by a factor of 100. A positive integer in the smallest currency unit, with no decimal point.Example:Smallest amount will be 1, which represents 0.01.For currencies that do not have denomination in cents, the smallest amount will be 100, which represents 1 IDR (Rp 1) or 1 VND (₫ 1). |
| * transaction_sn | string | Transaction serial number of the refund transaction in ShopeePay system. |
| * status | uint32 | Refer to Transaction Status for specific transaction statuses. |
| * transaction_type | uint32 | 15, referring to refund transaction type. Refer to Transaction Types for specific transaction types. |
| * create_time | uint32 | Create time of the transaction. |
| * update_time | uint32 | Update time of the transaction. |
| * user_id_hash | string | Identifier for customer that made the payment. |
| * merchant_ext_id | string | Unique identifier of merchant in merchant's system. |
| * store_ext_id | string | Unique identifier of store in merchant's system. |
| * terminal_id | string | If terminal ID info exists in transaction. |
| * payment_channel | uint32 | Indicates the source of fund used. Refer to Payment Channels for the respective source of fund. |
| co_funding | object | Will return empty if no co-funding involved.Note: This field is currently used in Thailand and Vietnam only. |
| * promotion_ext_name | string | Name of the promotion for merchant’s reference. |
| * redeemed_promotion_amount | int64 | Amount of the promotion benefit obtained by customer, inflated by a factor of 100. A positive integer in the smallest currency unit, with no decimal point.Note: for refund transaction types, this will be the amount of promotion benefit ShopeePay clawbacks from the customer in that refund transaction.Example:Smallest amount will be 1, which represents 0.01.For currencies that do not have denomination in cents, the smallest amount will be 100, which represents 1 IDR (Rp 1) or 1 VND (₫ 1). |
| * redeemed_promotion_type | uint32 | Refer to Promotion Types for specific transaction types. |
| * co_funding_cost_amount | int64 | Amount of cost born by merchant for the promotion benefit, inflated by a factor of 100. A positive integer in the smallest currency unit, with no decimal point.Note: for refund transaction types, this will be the amount of co-funding amount that the merchant will no longer be charged for due to that refund transaction.Example:Smallest amount will be 1, which represents 0.01.For currencies that do not have denomination in cents, the smallest amount will be 100, which represents 1 IDR (Rp 1) or 1 VND (₫ 1). |
Sample API Response
REQUEST
{"request_id": "input-unique-request-id-here","errcode": 0,"debug_msg": "success","transaction_list": {"reference_id": "refund_payment_abc12345","amount": 10000,"transaction_sn": "019703251690639893","status": 3,"transaction_type": 15,"create_time": 1647351920,"update_time": 1647351920,"user_id_hash": "15e455125fba426a4a2bb9145b3af2906813a7f222f6eab93b026ead62dc8d76","merchant_ext_id": "external-merchant","store_ext_id": "external-store","terminal_id": "A88","payment_channel": 1}}
Copy
Response Code
Please refer to the following description for a general explanation of the errcode returned during an API Response.
For a more detailed explanation, it is advisable to consult debug_msgfield. This field provides additional information that can offer valuable insights for troubleshooting.
Merchants may choose to display the debug_msg to their operators or staffs to facilitate prompt identification and resolution of the issue.
| Value | Description |
|---|---|
| -2 | A server dropped the connection |
| -1 | A server error occurred |
| 0 | Success |
| 1 | The request parameters is invalid or a mandatory parameter is empty |
| 2 | Permission denied, often due to invalid status |
| 4 | Not found, often due to merchant/store/user/transaction not found |
| 5 | Transaction is in processing status, use Check Transaction Status endpoint to query the updated status of the refund |
| 11 | Duplicated request |
| 42 | Insufficient balance |
| 304 | Unable to process refund due to payment exceeding refund validity period |
| 308 | Unable to process refund due to payment was made using non refundable voucher |
| 309 | Unable to process refund due to merchant does not have enough fee balance |
| 320 | Unable to process refund due to another ongoing refund request for the transaction |
| 321 | Unable to process refund due to insufficient balance |
| 401 | Unable to process refund due to requested refund amount exceeds transaction amount |
| 601 | Unable to process refund that does not meet the refund rules, such as:Refund operation is not allowed for the chosen merchant/storeThe transaction has already been refunded beforeRefund to a payment made by a different merchant/store is not allowedRefunds are not allowed during refund block periods, by default it is set at 12am to 5am based on the local timePlease note that the listed reasons are not exhaustive. |
| 602 | Request to refund an unsuccessful payment transaction |
| 1302 | Unable to process refund due to insufficient balance |
| 1906 | Unable to process refund due to transaction has been failed |
| 1908 | Service is temporarily down for scheduled maintenance |
| 300226 | Unable to refund to cross border merchants |