Notify Transaction Status
Notify Transaction Status
Use notifications to receive timely status updates for successful payment transactions. Merchant will need to provide a callback URL that can receive requests from ShopeePay notification server during onboarding.
Each callback request will contain a HMAC signature in the request header that should be verified to ensure authenticity of the callback content. This signature is generated using the ShopeePay issued secret key, assigned to the Merchant receiving the callback request.
It is essential for the merchant to validate that payment amount andpayment_reference_id matches the original /qr/create request before considering the payment as successful.
Note: merchants are highly recommended to implement Check Transaction Status endpoint to query the updated status of the transaction.
Common Fields
| Field | Type | Description |
|---|---|---|
| amount | int64 | Amount of the 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 identifier in ShopeePay system. |
| payment_method | uint32 | Indicates the product flows used. Refer to Point of Initiation for the respective product flows.Note: Do not set this as default value for validation |
| user_id_hash | string | Unique identifier of the customer making the payment. |
| merchant_ext_id | string | Unique identifier of the merchant in merchant’s system. |
| store_ext_id | string | Unique identifier of the store in merchant’s system. |
| terminal_id | string | This field is present when there is terminal_id in merchant’s MPM or CPM API request |
| 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.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). |
Additional Fields for Indonesia, Malaysia, Philippines and Singapore
| API | Field | Type | Description |
| payment_reference_id | string | Unique identifier of payment transaction generated by merchant. |
| payment_status | uint32 | Successful payment: payment_status = 1 Refer to Payment Status for the respective payment status. |
| reference_id | string | A new field introduced to generalise the notify callback for all types of transactions. This could be either |
| transaction_type | uint32 | A new field introduced to generalise the notify callback for all types of transactions. Refer to Transaction Types for specific transaction types. | |
| transaction_status | uint32 | A new field introduced to generalise the notify callback for all types of transactions. Refer to Transaction Status for specific transaction statuses. |
Additional Fields for Thailand and Vietnam
| API | Field | Type | Description |
|---|---|---|---|
| reference_id | string | A new field introduced to generalise the notify callback for all types of transactions. This could be either payment_reference_id or capture_reference_id. |
| transaction_type | uint32 | A new field introduced to generalise the notify callback for all types of transactions. Refer to Transaction Types for specific transaction types. | |
| transaction_status | uint32 | A new field introduced to generalise the notify callback for all types of transactions. Refer to Transaction Status for specific transaction statuses. |
Response Parameters
- In Indonesia, Malaysia, the Philippines, and Singapore, merchants are advised to respond with code=0 to acknowledge the notification. ShopeePay will send the notification only once.
- In Thailand and Vietnam, if a merchant does not respond with code=0, ShopeePay will resend the notification up to 2 times at 5-minute intervals.
| Field | Type | Mandatory | Description |
|---|---|---|---|
| errcode | int32 | Y | Error code to specify the error returned0: success |
| debug_msg | string | N | Debug message to provide more information |
Sample Callback for MPM, CPM and Checkout Payment Transaction
JS EXAMPLE
{"amount": 10000,"transaction_sn": "019703251690639893","payment_method": 2,"user_id_hash": "15e455125fba426a4a2bb9145b3af2906813a7f222f6eab93b026ead62dc8d76","merchant_ext_id": "external-merchant","store_ext_id": "external-store","terminal_id": "A88","payment_reference_id": "ref-must-be-unique","payment_status": 1,"payment_channel": 1}
Copy
Sample Callback for Link & Pay or Subscription Payment Transaction
JS EXAMPLE
{"amount": 10000,"transaction_sn": "019703251690639893","payment_method": 128,"user_id_hash": "15e455125fba426a4a2bb9145b3af2906813a7f222f6eab93b026ead62dc8d76","merchant_ext_id": "external-merchant","store_ext_id": "external-store","reference_id": "ref-must-be-unique","transaction_type": 13,"transaction_status": 3,"payment_channel": 1}
Copy