Merchant Presented Mode

Merchant Workflow

To accept the payment in this scenario, the merchant needs to complete the following steps:

Display a static QR or generate a dynamic QR for scanning
Once customer scans QR, merchant needs to handle the payment result returned

The following figure illustrates the workflow of accepting a payment in the Merchant Presented Mode payment scenario:

Merchant generates QR code by calling ShopeePay Create Dynamic QR for MPM endpoint.
Customer opens payment app, and scans the dynamic QR code presented by the merchant.
ShopeePay system returns the transaction result to the merchant. Meanwhile, customers will also see the updated payment result.
ShopeePay also sends an asynchronous message via Notify Transaction Status endpoint to inform merchants on the payment result.
Merchants can also call the Check Transaction Status endpoint to query the status of the transaction.
- If the response code is "Success" and latestTransactionStatus is 00, merchant can mark this transaction as successful.
- If the response code is "Failed", merchant can mark this transaction as failed.
- If the transaction is in a "Processing" status, please retry the request at an incremental time range of every 5 seconds (e.g., 5 seconds, 10 seconds, 15 seconds, and so on) up to a maximum of 100 seconds. If there is no response after 100 seconds, please retry the request at an incremental time range of every 5 minutes until the payment expires. Alternatively, merchants can call the Invalidate endpoint to terminate the transaction.
- If the transaction has no response, please retry the request at an incremental time range of every 5 seconds (e.g., 5 seconds, 10 seconds, 15 seconds, and so on) up to a maximum of 100 seconds. If there is no response after 100 seconds, please retry the request at an incremental time range of every 5 minutes until the payment expires.
- If customer can show evidence of payment success on their payment app, merchant may choose to consider payment as successful and wait for reconciliation process on T+1 to settle discrepancies with ShopeePay, if any.
For Refund, if the transaction is in Processing status or has no response, keep inquiring with an incremental frequency up to 24 hours.

Create Dynamic QR for MPM

Use this endpoint to generate a dynamic QR code containing the payment amount and unique partnerReferenceNo.
All API requests require a header. Refer to API Param Specification → Transaction Request

Specification

HTTP Method	POST
Service Code	47
Path	.../v1.0/qr/qr-mpm-generate
Version	v1.0

Request Parameters

Field	Type	Mandatory	Description
partnerReferenceNo	String	M	Unique identifier for request Accepts up to 64 characters
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 payment amount Accepted values: IDR
feeAmount	Object	O
value	String	C	Convenience fee amount charged by the merchant. This field is mandatory if `convenienceFeeIndicator` value is 02 or 03 For `convenienceFeeIndicator` = 03, specify the fee as percentage For 10% fee, enter 10.00
currency	String	C	Currency that is associated with the transaction fee amount Accepted values: IDR This field is mandatory if convenienceFeeIndicator value is 02 or 03.
merchantId	String	M	Unique identifier of merchant in merchant’s system. Accepts up to 64 characters.
validityPeriod	String	O	By default, the expiry time will be set to 1200 seconds (20 minutes), from the time the request was received. Accepts up to 432,000 seconds (5 days) from the time request was received If this field is filled, the QR code containing the `partnerReferenceNo` in this request will expire and payment that QR code will fail after the specified period. Using ISO 8601 timestamp format.
terminalId	String	O	Unique identifier of store terminal.
additionalInfo	Object	M
externalStoreId	String	M	Unique identifier of store in merchant system. Accepts up to 64 characters.
convenienceFeeIndicator	String	O	Convenience fee can be fixed, or percentage of the payment amount. Accepted values: 01 - Customer inputs fee amount 02 - Convenience fee is a fixed value, to be indicated in `feeAmount` 03 - Convenience fee is based on percentage of payment, to be indicated in `feeAmount`
promoIds	String	O	Comma separated eligible promoIds of 100 characters or less (up to 20), if any. These promoIds will be checked against promotional campaigns configured in ShopeePay to determine the valid reward amount the customer can receive for this transaction.
metadata	String	O	Additional information for the transaction. This field supports up to 3 fields and needs to be sent in this format {\”field1\”:\”{Data1}\”,\”field2\”:\”{Data2}\” ,\”field3\”:\”{Data3}\”}

Sample API Request

REQUEST

{
   "partnerReferenceNo": "input-unique-request-id-here",
   "amount": {
      "value": "10000.00",
      "currency": "IDR"
   },
   "feeAmount": {
      "value": "1000.00",
      "currency": "IDR"
   },
   "merchantId": "Merchant123",
   "validityPeriod": "2022-07-07T07:15:00+07:00",
   "terminalId": "T2903",
   "additionalInfo": {
      "externalStoreId": "Store123",
      "convenienceFeeIndicator": "02",
      "promoIds": "Promo1,Promo2",
      "metadata": "{"field1":"{Data1}","field2":"{Data2}" ,"field3":"{Data3}"}"
   }
}

Copy

Response Parameters

Field	Type	Mandatory	Description
responseCode	String	M	Error code to specify the error returned.
responseMessage	String	M	Debug message to provide more information.
qrContent	String	O	QR string in plain text.
qrUrl	String	O	URL to download QR image, URL is valid for 5 minutes.
additionalInfo	Object	O
storeName	String	O	Name of the store onboarded to ShopeePay.

Sample API Response

REQUEST

{
   "responseCode": "2004700",
   "responseMessage": "Successful",
   "qrContent": "00020101021226540016ID.CO.SHOPEE.WWW011893600918002024585002082024585052041234530336054041.0058021D5911test6007Bandung61054016362200516-1 July 20-126304D0A9",
   "qrUrl": "https://xxx.co.id/v3/merchant-host/qr/download?qr=K4aRLCjAqjXYxIFavFxz0EPRX5CfG4nnzgEauynlIL",
   "additionalInfo": {
      "storeName": "Test Account"
   }
}

Copy

Response Codes

Please refer to the following description for a general explanation of the responseCode returned during an API Response.

For a more detailed explanation, it is advisable to consult responseMessage. This field provides additional information that can offer valuable insights for troubleshooting.

Merchants may choose to display the responseMessage to their operators or staffs to facilitate prompt identification and resolution of the issue.

HTTP code	Service Code	Sub-error code	Response Code	Response Message	Partner Action
200	47	00	2004700	Successful	Mark MPM generate process to Success. Display QR to customer
400	47	00	4004700	Bad Request	Mark MPM generate process to Failed. Retry request with proper parameter
400	47	01	4004701	Invalid field format {fieldName} Invalid field format {timestamp} Invalid field format {validityPeriod} Invalid field format {promIds} Invalid field format {partnerReferenceNo}. Exceed maximum 64 characters Invalid field format {convenienceFeeIndicator} Invalid field format {terminalId} Invalid field format {metadata}. Exceed Maximum Characters Invalid field format {metadata}. Maximum JSON Key Exceeded Invalid field format {metadata}. Invalid JSON Key Name Invalid field format {metadata}	Mark MPM generate process to Failed. Retry request with proper parameter
400	47	02	4004702	Invalid mandatory field {fieldName} Invalid mandatory field {partnerReferenceNo} Invalid mandatory field {currency} Invalid mandatory field {externalStoreId} Invalid mandatory field {merchantId} Invalid mandatory field {merchantId}. Exceed maximum character length Invalid mandatory field {externalStoreId}. Exceed maximum character length Invalid mandatory field {feeAmount.value} Invalid Mandatory Field + {error message}	Mark MPM generate process to Failed. Retry request with proper parameter
400	47	13	4004713	Invalid amount. Fee amount does not support cents Invalid amount. Non-positive amount is not allowed	Mark MPM generate process to Failed. Retry request with proper parameter
401	47	00	4014700	Unauthorized. Invalid Client Key Unauthorized.{error message}	Mark MPM generate process to Failed. Retry request with proper parameter
401	47	01	4014701	Invalid Token	Mark MPM generate process to Failed. Retry request with proper parameter
403	47	02	4034702	Exceeds Transaction Amount Limit	Mark MPM generate process to Failed. Retry request with proper parameter
404	47	08	4044708	Invalid merchant Invalid store Invalid Field Format	Mark MPM generate process to Failed. Contact Shopeepay to check merchant/store status
404	47	13	4044713	Invalid amount. Currency does not support cents	Mark MPM generate process to Failed. Retry request with proper parameter
404	47	18	4044718	Inconsistent Request	Mark MPM generate process to Failed. Retry request with proper parameter
409	47	00	4094700	Conflict	Mark MPM generate process to Failed. Retry request periodically or consult to Shopeepay
500	47	00	5004700	General Error	Mark MPM generate process to Failed. Retry request periodically or consult to Shopeepay
500	47	01	5004701	Internal Server Error	Mark MPM generate process to Failed. Retry request periodically or consult to Shopeepay
504	47	00	5044700	Timeout	Mark MPM generate process to Failed. Retry request periodically or consult to Shopeepay

Invalidate QR for MPM

Use this endpoint to invalidate the payment reference id in a payment code for Merchant Presented Mode (MPM) if the order in the merchant's system is closed/canceled. Once the QR is invalidated successfully, the corresponding QR code containing the payment reference ID can no longer be used to make payment.
All API requests require a header. Refer to API Param Specification → Transaction Request

Specification

The following table is the specification of the API:

HTTP Method	POST
Service Code	77
Path	.../v1.0/qr/qr-mpm-cancel
Version	v1.0

Request Parameter

Field	Type	Mandatory	Description
originalPartnerReferenceNo	String	M	Unique identifier of the transaction client would like to invalidate/cancel.
merchantId	String	M	Unique identifier of merchant in merchant system.
externalStoreId	String	M	Unique identifier of store in merchant system.
reason	String	M	Cancellation reason. Accepts up to 256 characters.

Sample API Request

REQUEST

{
  "originalPartnerReferenceNo": "Testing-123",
  "merchantId": "Merchant123",
  "externalStoreId": "Store123",
  "reason": "Cancel order"
}

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.
cancelTime	String	C	Update time of the individual transaction. The value will be returned for successful invalidate request. Using ISO-8601 timestamp format.
originalReferenceNo	String	C	Transaction identifier in ShopeePay system that is shown to the customer. The value will be returned for successful payment.

Sample API Response

RESPONSE

{
  "responseCode": "2007700",
  "responseMessage": "Successful",
  "cancelTime": "2022-07-21T07:15:00+07:00",
  "originalReferenceNo": "123323887564698876"
}

Copy

Response Codes

Please refer to the following description for a general explanation of the responseCode returned during an API Response.

For a more detailed explanation, it is advisable to consult responseMessage. This field provides additional information that can offer valuable insights for troubleshooting.

Merchants may choose to display the responseMessage to their operators or staffs to facilitate prompt identification and resolution of the issue.

HTTP code	Service Code	Sub-error code	Response Code	Response Message	Partner Action
200	77	00	2007700	Successful	Mark MPM cancel process to Success. Mark MPM payment status to failed.
400	77	00	4007700	Bad Request	Mark MPM cancel process to Failed. Retry request with proper parameter
400	77	01	4007701	Invalid field format {fieldName}	Mark MPM cancel process to Failed. Retry request with proper parameter
400	77	02	4007702	Invalid mandatory field {fieldName} Invalid mandatory field {originalPartnerReferenceNo} Invalid mandatory field {merchantId}. Exceed maximum character length Invalid mandatory field {externalStoreId}. Exceed maximum character length Invalid Mandatory Field + {error message}
401	77	00	4017700	Unauthorized. Invalid Client Key Unauthorized.{error message}	Mark MPM cancel process to Failed. Retry request with proper parameter
401	77	01	4017701	Invalid Token	Mark MPM cancel process to Failed. Retry request with proper parameter
403	77	01	4037701	Feature Not Allowed	Mark MPM cancel process to Failed. Contact Shopeepay to check merchant/store supported product flow
403	77	06	4037706	Feature Not Allowed. Service Is Temporarily Down For Scheduled Maintenance	Mark MPM cancel process to Failed. Retry request periodically or consult to Shopeepay
403	77	15	4037715	Transaction Not Permitted. Transaction Already In Final State Transaction Not Permitted. Merchant Info Mismatch Transaction Not Permitted. QR Code Can Not Be Invalidated	Mark MPM cancel process to Failed. Request "Check MPM Transaction Status" to get final status
404	77	01	4047701	Transaction Not Found	Mark MPM cancel process to Failed. Retry request with proper parameter
404	77	08	4047708	Invalid Merchant Invalid Store Invalid {fieldName}	Mark MPM cancel process to Failed. Contact Shopeepay to check merchant/store status
409	77	00	4097700	Conflict	Mark MPM cancel process to Failed. Retry request periodically or consult to Shopeepay
500	77	00	5007700	General Error	Mark MPM cancel process to Failed. Retry request periodically or consult to Shopeepay
500	77	01	5007701	Internal Server Error	Mark MPM cancel process to Failed. Retry request periodically or consult to Shopeepay
504	77	00	5047700	Timeout	Mark MPM cancel process to Failed. Retry request periodically or consult to Shopeepay

Check MPM Transaction Status

Use this endpoint to query the status of a transaction across all supported service codes.

Check MPM Transaction Status API can’t be used for MPM transactions which are not made using ShopeePay Payment API.
All API requests require a header. Refer to API Param Specification → Transaction Request

Note:

While a '200xx00' response generally indicates a successful API call, the actual transaction might still be processing in the background. To confirm the latest status of your transaction, we strongly recommend referring to the latestTransctionStatus field in the API response. This will provide the most up-to-date information.

Specification

The following table is a specification of this API:

HTTP Method	POST
Service Code	51
Path	.../v1.0/qr/qr-mpm-query
Version	v1.0

Request Parameter

Field	Type	Mandatory	Description
originalPartnerReferenceNo	String	M	Unique identifier of the transaction merchant would like to query, which could be `partnerReferenceNo` to check payment transaction, or `partnerRefundNo` to check refund transaction
merchantId	String	M	Unique identifier of merchant in merchant’s system.
externalStoreId	String	M	Unique identifier of store in merchant’s system.
serviceCode	String	M	Service code of original transaction, which could be 47 (payment) or 78 (refund).
additionalInfo	String	M
value	String	M	Transaction amount., including cents Sample: 10.000,00 will be placed with 10000.00

Sample API Request

REQUEST

{
  "originalPartnerReferenceNo": "Testing-123",
  "merchantId": "Merchant123",
  "externalStoreId": "Store123",
  "serviceCode": "47",
  "additionalInfo": {
    "value": "10000.00"
  }
}

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
originalReferenceNo	String	C	Transaction identifier in ShopeePay system that is shown to the customer. The value will be returned for successful payment.
originalPartnerReferenceNo	String	O	Unique identifier of the transaction merchant would like to query, which could be `partnerReferenceNo` or `partnerRefundNo`
serviceCode	String	M	Service code of original transaction, which could be 47 (payment) or 78 (refund).
latestTransactionStatus	String	M	Refer to Transaction Status for specific transaction statuses
paidTime	String	C	Update time of the individual transaction. The value will be returned for successful payment. Using ISO-8601 timestamp format.
amount	Object	O
value	String	M	Transaction amount. Sample: 10.000,00 will be placed with 10000.00
currency	String	M	Currency that is associated with the refund amount Accepted values: IDR
terminalId	String	O	If terminal ID info exists in transaction.
additionalInfo	Object	O
createTime	String	O	Create time of the individual transaction. Using ISO-8601 timestamp format
productType	uint32	O	Indicates the payment method used. Refer to Product Types for the respective payment methods
transactionType	uint32	O	Refer to Transaction Types for specific transaction types
merchantId	String	O	Unique identifier of merchant’s in merchant system.
externalStoreId	String	O	Unique identifier of store in merchant’s system.
userIdHash	String	O	Unique identifier of the customer making the payment.
promoIdApplied	String	O	Comma separated eligible promoIds of 100 characters or less (up to 20), if any. These promoIds will be checked against promotional campaigns configured in ShopeePay to determine the valid reward amount the customer can receive for this transaction.
paymentChannel	int32	O	Indicates the source of fund used. Refer to Payment Channels for the respective source of fund.

Sample API Response

RESPONSE

{
   "responseCode": "2005100",
   "responseMessage": "Successful",
   "originalReferenceNo": "Payment-123",
   "originalPartnerReferenceNo": "Testing-123",
   "serviceCode": "47",
   "latestTransactionStatus": "00",
   "paidTime": "2022-07-20T07:20:00+07:00",
   "amount": {
      "value": "10000.00",
      "currency": "IDR"
   },
   "terminalId": "2903",
   "additionalInfo": {
      "productType": 2,
      "transactionType": 13,
      "createTime": "2022-07-20T07:05:00+07:00",
      "userIdHash": "15e455125fba426a4a2bb9145b3af2906813a7f222f6eab93b026ead62dc8d76",
      "merchantId": "Merchant123",
      "externalStoreId": "Store123",
      "promoIdApplied": "Promo1, Promo2",
      "paymentChannel": 1
   }
}

Copy

Response Codes

HTTP code	Service Code	Sub-error Code	Response Code	Response Message	Partner Action
200	51	00	2005100	Successful	Mark MPM payment to corresponding status according to response.additionalInfo.latestTransactionStatus. Retry request periodically if didn't get final status
400	51	00	4005100	Bad Request	Mark MPM Payment to Pending. Retry request with proper parameter
400	51	01	4005101	Invalid field format {fieldName} Invalid field format {serviceCode} Invalid Field Format {metadata}. Exceed Maximum Characters Invalid Field Format {metadata}. Maximum JSON Key Exceeded Invalid Field Format {metadata}. Invalid JSON Key Name Invalid Field Format {metadata} Invalid Field Form	Mark MPM Payment to Pending. Retry request with proper parameter
400	51	02	4005102	Invalid mandatory field {fieldName} Invalid mandatory field {partnerReferenceNo} Invalid mandatory field {merchantId/externalStoreId} Invalid mandatory field {merchantId}. Exceed maximum character length Invalid mandatory field {externalStoreId}. Exceed maximum character length Invalid Amount. Amount cannot contain cents Invalid Mandatory Field + {error message}
401	51	00	4015100	Unauthorized Invalid Client Key Unauthorized.{error message}	Mark MPM Payment to Pending. Retry request with proper parameter
401	51	01	4015101	Invalid Token	Mark MPM Payment to Pending. Retry request with proper parameter
404	51	01	4045101	Transaction Not Found	Mark MPM Payment to Failed
404	51	08	4045108	Entity not found Invalid Field Format Invalid Merchant, Status Is Not Active Invalid Store, Status is Not Active	Mark MPM Payment to Pending. Retry request periodically or consult to Shopeepay
404	51	13	4045113	Invalid Amount. Mismatch With Original Transaction Invalid Amount. Non Positive Amount Is Not Allowed	Mark MPM Payment to Pending. Retry request with proper parameter
409	51	00	4095100	Conflict	Mark MPM Payment to Pending. Retry request periodically or consult to Shopeepay
500	51	00	5005100	General Error	Mark MPM Payment to Pending. Retry request periodically or consult to Shopeepay
500	51	01	5005101	Internal Server Error	Mark MPM Payment to Pending. Retry request periodically or consult to Shopeepay
504	51	00	5045100	Timeout	Mark MPM Payment to Pending. Retry request periodically or consult to Shopeepay

Refund Payment

Use this endpoint to request a refund for a successful transaction. Refunds are subject to refund conditions.

HTTP Method	POST
Service Code	78
Path	.../v1.0.2/qr/qr-mpm-refund
Version	v1.0.2

Refer to Refund Payment endpoint for the detail request and response parameters.

Notify Transaction Status

Note: Merchant needs to confirm that both the payment amount and the originalPartnerReferenceNo correspond to the original /qr/qr-mpm-generate request before considering the payment successful.

HTTP Method	POST
Service Code	52
Path	.../v1.0/debit/notify
Version	v1.0

Refer to Notify Transaction Status endpoint for the detail request body and response parameters.

Merchant Presented Mode

Merchant Workflow

Create Dynamic QR for MPM

Specification

Request Parameters

Sample API Request

REQUEST

Response Parameters

Sample API Response

REQUEST

Response Codes

Invalidate QR for MPM

Specification

Request Parameter

Sample API Request

REQUEST

Response Parameter

Sample API Response

RESPONSE

Response Codes

Check MPM Transaction Status

Specification

Request Parameter

Sample API Request

REQUEST

Response Parameter

Sample API Response

RESPONSE

Response Codes

Refund Payment

Notify Transaction Status

On this page