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
CPM MPM Checkout	payment_reference_id	string	Unique identifier of payment transaction generated by merchant.
CPM MPM Checkout	payment_status	uint32	Successful payment: payment_status = 1 Refer to Payment Status for the respective payment status.
Link & Pay Subscription	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.

Additional Fields for Thailand and Vietnam

API	Field	Type	Description
CPM MPM Checkout Link & Pay Subscription	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.

API

Field

Type

Description

CPM
MPM
Checkout
Link & Pay
Subscription

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.

|-----------|----------|---------------|----------------------------------------------------|

| errcode | int32 | Y | Error code to specify the error returned0: success |

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

Notify Transaction Status