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 signature in the request header that should be verified to ensure authenticity of the callback content. It is essential for the Merchant to validate that payment amount and payment originalPartnerReferenceNo matches the original transaction.

Note:

Callbacks are one-time events: ShopeePay will send a callback notification only once per transaction. There are no automatic retries.
Accurate response is crucial: Merchants must send a valid HTTP response to acknowledge the callback.
Transaction status verification: To get the latest transaction status, merchants must use the "Check Transaction Status" endpoint.

Callback URL specification

To receive real-time updates on your transactions, please provide a dedicated product endpoint (URL) in your API integration. This endpoint will allow our system to notify you automatically about the status of each transaction.

The following table is the specification of the API:

	MPM	CPM	Checkout with ShopeePay, Link & Pay, Subscription, Auth & Capture
HTTP Method	POST	POST	POST
Service Code	52	79	56
Path	.../v1.0/qr/qr-mpm-notify	.../v1.0/qr/qr-cpm-notify	.../v1.0/debit/notify
Version	v1.0	v1.0	v1.0

Request Parameter

Common Fields

Field	Type	Mandatory	Description
originalReferenceNo	String	M	Transaction identifier in ShopeePay system.
originalPartnerReferenceNo	String	M	Unique identifier of payment transaction generated by client.
externalStoreId	String	M	Unique identifier of store in merchant system.
amount	Object	M
value	String	M	Transaction amount Sample: 10.000,00 will be placed with 10000.00
currency	String	M	Currency that is associated with the transaction. Accepted values: IDR
latestTransactionStatus	String	M	Refer to Transaction Status for the respective payment status.
additionalInfo	Object	M
productType	uint32	M	Indicates the payment product used. Refer to Product Types for the respective payment product.
userIdHash	String	M	Unique identifier of the customer making the payment.
terminalId	String	M	Terminal id in merchant’s MPM/CPM API request. This field will be empty if the payment flow is not MPM or CPM.
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	additionalInfo	Object	M
	merchantId	String	M	Unique indentifier of merchant in merchant system
CPM Checkout with ShopeePay Link & Pay Subscription	merchantId	String	M	Unique identifier of merchant in merchant system
Checkout with ShopeePay Link & Pay Subscription	additionalInfo	Object	M
	transactionType	unit32	M	Refer to Transaction Types for specific transaction types

Sample API Request

Sample API Request for MPM (Merchant Presented Mode)

REQUEST

{
   "originalReferenceNo": "Payment-123",
   "originalPartnerReferenceNo": "Testing-123",
   "externalStoreId": "Store123",
   "amount": {
      "value": "10000.00",
      "currency": "IDR"
   },
   "latestTransactionStatus": "00",
   "additionalInfo": {
      "merchantId": "Merchant123",
      "productType": 2,
      "userIdHash": "15e455125fba426a4a2bb9145b3af2906813a7f222f6eab93b026ead62dc8d76",
      "terminalId": "T2903",
      "paymentChannel": 1
   }
}

Copy

Sample API Request for CPM (Customer Presented Mode)

REQUEST

{
  "originalReferenceNo": "Payment-123",
  "originalPartnerReferenceNo": "Testing-123",
  "merchantId": "Merchant123",
  "externalStoreId": "Store123",
  "amount": {
    "value": "35000.00",
    "currency": "IDR"
  },
  "latestTransactionStatus": "00",
  "additionalInfo": {
    "productType": 16,
    "userIdHash": "15e455125fba426a4a2bb9145b3af2906813a7f222f6eab93b026ead62dc8d76",
    "terminalId": "21553266",
    "paymentChannel":1
  }
}

Copy

Sample API Request for Link & Pay, Subscription

REQUEST

{
   "originalReferenceNo": "Payment-123",
   "originalPartnerReferenceNo": "Testing-123",
   "merchantId": "Merchant123",
   "externalStoreId": "Store123",
   "amount": {
      "value": "10000.00",
      "currency": "IDR"
   },
   "latestTransactionStatus": "00",
   "additionalInfo": {
      "transactionType": 13,
      "productType": 128,
      "userIdHash": "15e455125fba426a4a2bb9145b3af2906813a7f222f6eab93b026ead62dc8d76",
      "terminalId": "T2903",
      "paymentChannel": 1
   }
}

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

Sample API Response

RESPONSE

{
   "responseCode": "2005600",
   "responseMessage": "Successful"
}

Copy

Processing Callback Notifications

This section describes how to process incoming callback notifications and validate their authenticity using the provided signature

Validating the Request Signature

Upon receiving the API callback, Client should verify the signature of the callback in the following ways.

1. Take the signature from HTTP header "X-SIGNATURE" in the callback request from ShopeePay

Example signature:

EXAMPLE


hnha4pl/3qPxBlAoRLvxzQzCt3wWqBHDTQfRkvI9o7ZDkwsM9NI0YxZVkb/TyDu7wrkv7EVubMihyt4Kn1cjpXoU9MRQ2MHFAsN9tm3R7Qj0kQwvmhCsjOSp9zPhBfT99Syg4TdjHpLPMnxPHEmarZKHPzCdcJCtdz1ohZ6ilamyjLazICXpsezf4V3bZSiXMTS1CB7r3Nc0FFq6x2dMTCV0FU0/rJT7TVtntpgHee2xtcJIPpAqb+zyEAeyBaC5oGtTqlgd5D/bmAbi+t8wPdMTWC0xVpzoHdALOPoStwaxooMiGBsuGYz5xEgCFYGPOYN5dkPS/QJHvd+DhxhbGA==

Copy

2. Generate stringToSign based on this following format:

EXAMPLE

HTTPMethod + ":" + callbackURL + ":" + Hex(SHA256(requestBody)) + ":" + timestamp

Copy

Raw JSON Request Body:

REQUEST

{"originalReferenceNo":"Payment-123","originalPartnerReferenceNo":"Testing-123","externalStoreId":"Store123","amount":{"value":"10000.00","currency":"IDR"},"latestTransactionStatus":"00","additionalInfo":{"merchantId":"Merchant123","productType":2,"userIdHash":"15e455125fba426a4a2bb9145b3af2906813a7f222f6eab93b026ead62dc8d76","terminalId":"T2903","paymentChannel":1}}

Copy

Compute the SHA256 hash of the raw JSON request body (as received, without any modifications)
Convert the resulting hash value to a lowercase hexadecimal string.
- Example (using the JSON payload above): The SHA256 hash of the example JSON payload, converted to a lowercase hexadecimal string, is: 815174348d76ccfbd916c539ad21a494fa22d1be67621cd836e33f374cb4dad5

Note:

The value of timestamp is taken from the HTTP header "X-TIMESTAMP" in the callback request.
ShopeePay uses full path including the domain for merhant’s callbackURL

stringToSign example:

EXAMPLE


POST:https://example.callback.com/Shopee/v1.0/debit/notify:2ae8474e00b1a65fc67cba1b4f6446b94bb50a0fc9f575ae10d545a2ddc98068:2024-03-04T08:44:30+07:00

Copy

3. Verify the correctness of the signature based on Asymmetric SHA-256withRSA encryption using ShopeePay public key. Example code in various programming languages can be found in the "Callback Signature Validation" section.

Request Body Parsing and Response Handling

After validating the signature, parse the request body to extract essential information such as originalPartnerReferenceNo (merchant Ref Id) and latestTransactionStatus (status of the transaction). Here is an example of a callback request in JSON format:

REQUEST

{
   "originalReferenceNo": "Payment-123",
   "originalPartnerReferenceNo": "Testing-123",
   "externalStoreId": "Store123",
   "amount": {
      "value": "10000.00",
      "currency": "IDR"
   },
   "latestTransactionStatus": "00",
   "additionalInfo": {
      "merchantId": "Merchant123",
      "productType": 2,
      "userIdHash": "15e455125fba426a4a2bb9145b3af2906813a7f222f6eab93b026ead62dc8d76",
      "terminalId": "T2903",
      "paymentChannel": 1
   }
}

Copy

Acknowledge the notification with the required Response

After verifying the signature and confirming the notification is from ShopeePay, regardless of the transaction status, you need to send a response to Shopeepay to acknowledge the notification

The response must contain the following fields:

RESPONSE


{
   "responseCode": "2005600",
   "responseMessage": "Successful"
}

Copy

Notify Transaction Status