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", 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 up to 24 hours. 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 up to 24 hours.
- 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.

Create Dynamic QR for MPM

Use this endpoint to generate a dynamic QR code containing the payment amount and unique payment reference ID.

URL: "/v3/merchant-host/qr/create"

Request Parameters

Field	Type	Mandatory	Description
request_id	string	Y	Unique identifier for request, accepts up to 64 characters.
amount	int64	Y	Amount used for the payment as integer, inflated by a factor of 100. A positive integer in the smallest currency unit, with no decimal point.
currency	string	Y	Currency that is associated with the payment amount.
merchant_ext_id	string	Y	Unique identifier of merchant in merchant's system.
store_ext_id	string	Y	Unique identifier of store in merchant's system.
payment_reference_id	string	Y	Unique identifier of transaction generated by merchant.
qr_validity_period	uint32	N	By default, the expiry time will be set to 1200 seconds (20 minutes), from the time the request was received.
expiry_time	uint32	N	Unix timestamp.
terminal_id	string	N	Unique identifier of store terminal.
convenience_fee_indicator	string	N	Convenience fee can be fixed, or percentage of the payment amount.
convenience_fee_fixed	int64	C	Required if convenience fee is a fixed fee as indicated by convenience fee indicator
convenience_fee_percentage	uint32	C	Required if convenience fee is percentage as indicated by convenience fee indicator.
promo_ids	string	N	Comma separated eligible `promo_ids` of 100 characters or less (up to 20), if any.
additional_info	string	N	Additional information will be in json format.

Sample API Request

REQUEST

{
    "request_id": "input-unique-request-id-here",
    "amount": 100, 
    "currency": "IDR",
    "store_ext_id": "external-store",
    "merchant_ext_id": "external-merchant",
    "payment_reference_id": "ref-must-be-unique",
    "qr_validity_period": 10000,
    "convenience_fee_indicator": 02,
    "convenience_fee_fixed": 5,
    "promo_ids": "1234567890, 0987654321",
    "additional_info": "{\"field1\":\"Name\",\"field2\":\"Address\" ,\"field3\":\"Number\"}"
}

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.
store_name	string	Name of the store onboarded to Shopeepay.
qr_content	string	QR string in plain text.
qr_url	string	URL to download QR image, URL is valid for 5 minutes.

Sample API Response

RESPONSE

{
    "request_id": "input-unique-request-id-here",
    "errcode": 0,
    "debug_msg": "success",
    "store_name": "external-store",
    "qr_content": "00020101021226620016ID.CO.SHOPEE.WWW01189360091800202458500208202458500304NONE52041234530336054041.005802ID5911kiendl-test6012KOTA BANDUNG61054016362300520CsB-15 Mar 2021-ID-20702A1630424FA",
    "qr_url": "https://api.uat.wallet.airpay.co.id/v3/merchant-host/qr/download?qr=MD6r9iQbVGCoYlI7CW0p3fyW2xhsAZE0W9uDd6cRuL"
}

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_msg. 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. Please use Check Transaction Status endpoint to query the updated status of the payment.
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
11	Duplicated request
15	Payment amount exceeded payment limit
16	Payment amount did not meet payment limit
50	The request parameters is invalid due to payload sent is not a valid JSON
627	The request parameters is invalid due to promo ID exceeded limit
1800	A server error occurred
1908	Service is temporarily down for scheduled maintenance