Merchant Presented Mode

Merchant Workflow

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

  1. Display a static QR or generate a dynamic QR for scanning

  2. 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:

  1. Merchant generates QR code by calling ShopeePay Create Dynamic QR for MPM endpoint.
  2. Customer opens payment app, and scans the dynamic QR code presented by the merchant.
  3. ShopeePay system returns the transaction result to the merchant. Meanwhile, customers will also see the updated payment result.
  4. ShopeePay also sends an asynchronous message via Notify Transaction Status endpoint to inform merchants on the payment result.
  5. 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

FieldTypeMandatoryDescription
request_idstringYUnique identifier for request, accepts up to 64 characters.
amountint64YAmount used for the payment as integer, inflated by a factor of 100. A positive integer in the smallest currency unit, with no decimal point.
currencystringYCurrency that is associated with the payment amount.
merchant_ext_idstringYUnique identifier of merchant in merchant's system.
store_ext_idstringYUnique identifier of store in merchant's system.
payment_reference_idstringYUnique identifier of transaction generated by merchant.
qr_validity_perioduint32NBy default, the expiry time will be set to 1200 seconds (20 minutes), from the time the request was received.
expiry_timeuint32NUnix timestamp.
terminal_idstringNUnique identifier of store terminal.
convenience_fee_indicatorstringNConvenience fee can be fixed, or percentage of the payment amount.
convenience_fee_fixedint64CRequired if convenience fee is a fixed fee as indicated by convenience fee indicator
convenience_fee_percentageuint32CRequired if convenience fee is percentage as indicated by convenience fee indicator.
promo_idsstringNComma separated eligible promo_ids of 100 characters or less (up to 20), if any.
additional_infostringNAdditional 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\"}"
}
arrow-svg

Copy

Response Parameters

FieldTypeDescription
request_idstringUnique identifier for request.
errcodeint32Error code to specify the error returned.
debug_msgstringDebug message to provide more information.
store_namestringName of the store onboarded to Shopeepay.
qr_contentstringQR string in plain text.
qr_urlstringURL 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"
}
arrow-svg

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.

ValueDescription
-2A server dropped the connection
-1A server error occurred. Please use Check Transaction Status endpoint to query the updated status of the payment.
0Success
1The request parameters is invalid or a mandatory parameter is empty
2Permission denied, often due to invalid status
4Not found, often due to merchant/store/user/transaction not found
11Duplicated request
15Payment amount exceeded payment limit
50The request parameters is invalid due to payload sent is not a valid JSON
627The request parameters is invalid due to promo ID exceeded limit
1800A server error occurred
1908Service is temporarily down for scheduled maintenance