Customer Presented Mode (CPM)

Merchant Workflow

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

Identify and verify the QR code
Initiate a payment request
Handle the payment result returned

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

Customer opens a payment app, and presents a payment code (QR or barcode) to the merchant.
Merchant scans the customer's payment code.
Merchant sends a payment request to ShopeePay via Create CPM Payment endpoint.
ShopeePay system returns the transaction result to the merchant. Meanwhile, customers will also see the updated payment result.
- When ShopeePay returns "Processing" for a payment transaction, it indicates that the payment process is still ongoing and pending further customer action to select payment method to complete the payment. This case would most likely happen when customer selects SPayLater as payment method.
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, the merchant can mark this transaction as successful.
- If the response code is "Failed", the merchant can mark this transaction as failed.
- If the transaction is in a "Processing" status or 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 a Processing status or has no response, keep inquiring with an incremental frequency up to 24 hours.

Create CPM Payment

Use this endpoint to initiate a payment request after scanning a customer's payment code
All API requests require a header. Refer to API Param Specification → Transaction Request

Specification

The following table is a specification of this API:

HTTP Method	POST
Service Code	60
Path	../v1.0.2/qr/qr-cpm-payment
Version	v1.0.2

Request Parameters

Field	Type	Mandatory	Description
partnerReferenceNo	String	M	Unique identifier for request Accepts up to 64 characters.
qrContent	String	M	QR content from the user’s CPM QR code.
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
merchantId	String	M	Unique identifier of merchant in merchant’s system. Accepts up to 64 characters.
externalStoreId	String	M	Unique identifier of store in merchant’s system. Accepts up to 64 characters.
expiryTime	String	O	The transaction with the corresponding partnerReferenceNo in this request will fail after the specified expiry time. Expiry time will have a min value of 30s. Sample: `2020-12-21T17:21:41+07:00`
terminalId	String	O	Terminal ID refers to the Point of Sale terminal in a store.
additionalInfo	Object	O
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",
  "qrContent": "hQVDUFYwMWFiTwegAAAGAiAgUAdRUklTQ1BNWgqTYAkYMABRhWgPnyUCVoCfdi9kLd4UOTE4MDM1NjIxNzE2NjA4OTE3NDnEBIATEA/FAQ/HCVNob3BlZVBhecsBAWMLn3QINjA4OTE3NDk=",
  "amount": {
    "value": "10000.00",
    "currency": "IDR"
  },
  "merchantId": "Merchant123",
  "externalStoreId": "2233",
  "expiryTime": "2020-12-21T17:21:41+07:00",
  "terminalId": "T2903",
  "additionalInfo": {
    "promoIds": "Promo1,Promo2",
    "metadata": "{\"field1\":\"Data1\",\"field2\":\"Data2\" ,\"field3\":\"Data3\"}" 
  }
}

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.
referenceNo	String	C	Transaction identifier in ShopeePay system. Will be filled upon successful transaction.
partnerReferenceNo	String	O	Unique identifier of payment transaction generated by merchant.
transactionDate	String	O	Create time of the transaction. Using ISO-8601 timestamp format.
additionalInfo	Object	O
updateTime	String	O	Update time of the transaction. Using ISO-8601 timestamp format.
transactionType	uint32	O	13 Refer to Transaction Types for specific transaction types.
merchantId	String	O	Unique identifier of merchant in merchant’s system.
externalStoreId	String	O	Unique identifier of store in merchant’s system.
terminalId	String	O	Terminal ID refers to the Point of Sale terminal in a store.
userIdHash	String	O	Unique identifier of the user making the payment.
latestTransactionStatus	String	O	Refer to Transaction Status for specific transaction statuses
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": "2006000",
   "responseMessage": "Successful",
   "referenceNo": "Payment-123",
   "partnerReferenceNo": "input-unique-request-id-here",
   "transactionDate": "2022-07-07T07:15:00+07:00",
   "additionalInfo": {
      "updateTime": "2022-07-07T07:15:01+07:00",
      "transactionType": 13,
      "merchantId": "Merchant123",
      "externalStoreId": "Store123",
      "terminalId": "T2903",
      "userIdHash": "15e455125fba426a42bb9145b3af2906813a7f222f6eab93b026ead62dc8d76",
      "latestTransactionStatus": "00",
      "promoIdApplied": "Promo1,Promo2",
      "paymentChannel": 1
   }
}

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	60	00	2006000	Successful	Mark CPM payment process to corresponding status according to response.additionalInfo.latestTransactionStatus. Retry request "Check CPM Transaction Status" periodically if didn't get final status
400	60	00	4006000	Bad Request	Mark CPM Payment process to Failed. Retry request with proper parameter
400	60	01	4006001	Invalid Field Format Invalid mandatory field externalStoreId Invalid Field Format additionalInfo. Exceed Maximum Characters Invalid Field Format {metadata}	Mark CPM Payment process to Failed. Retry request with proper parameter
400	60	02	4006002	Invalid mandatory field {qrContent} Invalid mandatory field {merchantId}. Exceed maximum character length Invalid mandatory field {externalStoreId}. Exceed maximum character length Invalid mandatory field partnerReferenceNo Invalid Mandatory field partnerReferenceNo. Exceed maximum characters Invalid mandatory field merchantId Invalid mandatory field merchantId. Exceed maximum characters Invalid mandatory field externalStoreId Invalid mandatory field {qrContent} Invalid amount Amount cannot be non-positive Payment amount exceeds max amount limit Invalid mandatory field currency Currency and region are non-matching Invalid Mandatory Field + {error message}	Mark CPM Payment process to Failed. Retry request with proper parameter
401	60	00	4016000	Unauthorized.{error message}	Mark CPM Payment process to Failed. Retry request with proper parameter
401	60	01	4016001	Invalid Token	Mark CPM Payment process to Failed. Retry request with proper parameter
403	60	00	4036000	Timeout	Mark CPM Payment process to Pending. Retry request "Check CPM Transaction Status" to get final status.
403	60	01	4036001	Feature Not Allowed. Selected Payment Channel Is Disabled For Merchant	Mark CPM Payment process to Failed. Retry request periodically or consult to Shopeepay
403	60	02	4036002	Exceeds Transaction Amount Limit	Mark CPM Payment process to Failed. Try to adjust the order amount
403	60	03	4036003	Suspected Fraud	Mark CPM Payment process to Failed. Retry request periodically or consult to Shopeepay
403	60	05	4036005	Do Not Honor. User Is Banned Do Not Honor. User Is Locked Do Not Honor. User Is Deleted Do Not Honor. User Is Not Activated Do Not Honor. User Is Not Found	Mark CPM Payment process to Failed. Retry request with proper parameter or can contact Shopeepay to check the user/account status
403	60	06	4036006	Feature Not Allowed. Service Is Temporarily Down For Scheduled Maintenance	Mark CPM Payment process to Failed. Retry request periodically or consult to Shopeepay
403	60	14	4036014	Insufficient Funds Insufficient Funds. Insufficient SPayLater Credit Limit	Mark CPM Payment process to Failed. Retry later or change payment channel
403	60	15	4036015	Transaction Not Permitted. Merchant Is Trying To Make Payment To Their Own User Account Transaction Not Permitted. Unable To Use Coin Transaction Not Permitted. Payment Channel Is Not Supported Transaction Not Permitted. Amount Not Meet Minimum Spend Voucher Transaction Not Permitted. Promo_ids Is Not Matched Transaction Not Permitted. Promo_ids Has Been Used Transaction Not Permitted. Promo_ids Not Applicable Transaction Not Permitted. Promo_ids Not Match With Store Transaction Not Permitted. Voucher Is Expired Transaction Not Permitted. Payment Channel Selected By The User Currently May Not Used For This Transaction. Please Advise The User To Select Another Payment Method And Try Again Transaction Not Permitted. There Is An Ongoing Payment For This Transaction Transaction Not Permitted. Cashback Is Not Allowed Transaction Not Permitted. OTP or 3DS Verification Failed	Mark CPM Payment process to Failed. Retry request with proper parameter
404	60	01	4046001	qrContent Expired qrContent Not Found	Mark CPM Payment process to Failed. Retry request with another QR code
404	60	08	4046008	Invalid Merchant, Status is Not Active Invalid Store, Status is Not Active Invalid Field format Invalid Merchant	Mark CPM Payment process to Failed. Retry request periodically or contact Shopeepay to check merchant/store status
404	60	13	4046013	Invalid amount. Currency doesn't support cents	Mark CPM Payment process to Failed. Retry request with proper parameter
404	60	18	4046018	Inconsistent Request	Mark CPM Payment process to Failed. Retry request with proper parameter
409	60	00	4096000	Conflict	Mark CPM Payment process to Pending. Retry request "Check CPM Transaction Status" to get final status
500	60	01	5006001	Internal Server Error	Mark CPM Payment process to Pending. Retry request "Check CPM Transaction Status" to get final status
504	60	00	5046000	Timeout	Mark CPM Payment process to Pending. Retry request "Check CPM Transaction Status" to get final status

Check CPM Transaction Status

Use this endpoint to query the status of a CPM transaction.
Check CPM Transaction Status API can't be used for CPM transactions that 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 LatestTransactionStatus 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	61
Path	.../v1.0/qr/qr-cpm-query
Version	v1.0

Request Parameters

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.
additionalInfo	String	M
value	String	M	Transaction amount Sample: 10.000,00 will be placed with 10000.00
serviceCode	String	M	Service code of original transaction, which could be 60 (create CPM payment) or 80 (refund).

Sample API Request

REQUEST

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

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
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`.
latestTransactionStatus	String	M	Refer to Transaction Status for specific transaction statuses
paidTime	String	M	Update time of the individual transaction. Using ISO-8601 timestamp format.
additionalInfo	Object	O
value	String	O	Transaction amount. Sample: 10.000,00 will be placed with 10000.00
currency	String	O	Currency that is associated with the refund amount Accepted values: IDR
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
serviceCode	String	O	Service code of original transaction, which could be 60 (create CPM payment) or 80 (refund).
merchantId	String	O	Unique identifier of merchant in merchant’s system.
externalStoreId	String	O	Unique identifier of store in merchant’s system.
userIdHash	String	O	Unique identifier of the customer making the payment.
terminalId	String	O	If terminal ID info exists in transaction.
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": "2006100",
  "responseMessage": "Successful",
  "originalReferenceNo": "Payment-123",
  "originalPartnerReferenceNo": "Testing-123",
  "latestTransactionStatus": "00",
  "paidTime": "2022-07-07T15:00:01+07:00",
  "additionalInfo": {
    "value": "100.00",
    "currency": "IDR",
    "createTime": "2022-07-07T15:00:00+07:00",
    "productType": 4,
    "transactionType": 13,
    "serviceCode": "60",
    "merchantId": "externalmerchant",
    "externalStoreId": "externalstore",
    "terminalId": "T2903",
    "userIdHash": "15e455125fba426a4a2bb9145b3af2906813a7f222f6eab93b026ead62dc8d76",
    "promoIdApplied": "Promo1, Promo2",
    "paymentChannel": 1
  }
}

Copy

Response Code

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	61	00	2006100	Successful	Mark CPM payment to corresponding status according to response.additionalInfo.latestTransactionStatus. Retry request periodically when didn't get final status
400	61	00	4006100	Bad Request	Mark CPM Payment to Pending. Retry request with proper parameter
400	61	01	4006101	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 mandatory field {value}, Non-Positive Amount	Mark CPM Payment to Pending. Retry request with proper parameter
400	61	02	4006102	Invalid mandatory field {fieldName} Invalid mandatory field {partnerReferenceNo} Invalid mandatory field {merchantId}. Exceed maximum character length Invalid mandatory field {externalStoreId}. Exceed maximum character length Invalid mandatory field {merchantId/externalStoreId} Invalid Amount. Amount cannot contain cents Invalid Mandatory Field + {error message}	Mark CPM Payment to Pending. Retry request with proper parameter
400	61	08	4006108	Invalid Field format Invalid Merchant	Mark CPM Payment to Pending. Retry request with proper parameter
401	61	00	4016100	Unauthorized. Invalid Client Key Unauthorized.{error message}	Mark CPM Payment to Pending. Retry request with proper parameter
401	61	01	4016101	Invalid Token	Mark CPM Payment to Pending. Retry request with proper parameter
403	61	08	4036108	Invalid Merchant, Status Is Not Active Invalid Store, Status Is Not Active	Mark CPM Payment to Pending. Retry request periodically or consult to Shopeepay
404	61	01	4046101	Transaction not found	Mark CPM Payment to Failed
404	61	08	4046108	Entity not found	Mark CPM Payment to Pending. Retry request periodically or consult to Shopeepay
404	61	13	4046113	Invalid amount. Mismatch with original transaction Invalid Amount. Non Positive Amount Is Not Allowed	Mark CPM Payment to Pending. Retry request with proper parameter
409	61	00	4096100	Conflict	Mark CPM Payment to Pending. Retry request periodically or consult to Shopeepay
500	61	00	5006100	General Error	Mark CPM Payment to Pending. Retry request periodically or consult to Shopeepay
500	61	01	5006101	Internal Server Error	Mark CPM Payment to Pending. Retry request periodically or consult to Shopeepay
504	61	00	5046100	Timeout	Mark CPM 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	80
Path	.../v1.0/qr/qr-cpm-refund
Version	v1.0

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-cpm-payment request before considering the payment successful.

HTTP Method	POST
Service Code	79
Path	.../v1.0/qr/qr-cpm-notify
Version	v1.0

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

Customer Presented Mode (CPM)

Merchant Workflow

Create CPM Payment

Specification

Request Parameters

Sample API Request

REQUEST

Response Parameter

Sample API Response

RESPONSE

Response Codes

Check CPM Transaction Status

Specification

Request Parameters

Sample API Request

REQUEST

Response Parameters

Sample API Response

RESPONSE

Response Code

Refund Payment

Notify Transaction Status

On this page