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", 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 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 CPM Payment

Use this endpoint to initiate a payment request after scanning a customer’s payment code.

URL: "/v3/merchant-host/transaction/payment/create"

Request Parameters

Field	Type	Mandatory	Description
request_id	string	Y	Unique identifier for request, accepts up to 64 characters.
amount	uint64	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.
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_code	string	Y	Payment code is the QR/barcode content from the customer’s QR code. If there’s no national QR code standard defined on a national level, this code starts with “918” and contains 20 digits.
payment_reference_id	string	Y	Unique identifier of transaction generated by merchant.
currency	string	Y	Currency that is associated with the payment amount. Specify the three-letter ISO currency code following the ISO 4217 standard. Currently supports IDR, MYR, PHP, SGD, THB, and VND.
validity_period	uint32	N	By default, the expiry time will be set to 120 seconds. If this field is filled, the order associated with the corresponding `payment_reference_id` in this request will expire after the specified validity period (in seconds). The minimum validity period is 120 seconds and the maximum allowable value is 5 days. Note: The system will return an error if both `validity_period` and`expiry_time` parameters are used simultaneously.
expiry_time	uint32	N	Unix timestamp. By default, the expiry time will be set to 120 seconds. If this field is filled, the order associated with the corresponding `payment_reference_id` in this request will be invalid after the specified timestamp. The minimum expiry time allowed will be 30 seconds from the request time and the maximum acceptable expiry time is 5 days. Note: The system will return an error if both `validity_period` and`expiry_time` parameters are used simultaneously.
terminal_id	string	N	Terminal ID refers to the Point of Sale terminal in a store.
promo_ids	string	N	Comma separated eligible `promo_ids` of 100 characters or less (up to 20), if any. These `promo_ids` will be checked against promotional campaigns configured in ShopeePay to determine the valid reward amount the customer can receive for this transaction.
additional_info	string	N	Additional information will be in json format. 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

{
    "request_id": "input-unique-request-id-here",
    "amount": 10000,
    "merchant_ext_id": "external-merchant",
    "store_ext_id": "external-store",
    "payment_code":"hQVDUFYwMWEzTwegAAAGAiAgUAdRUklTQ1BNWgqTYAkYMQEVOAYPXyAAnyUCgGBjC590CAAAAAAAAAAAYilkJ94UOTE4NDU3OTQyMTE2NDczNTE4NzDEBIABQA/HCVNob3BlZVBheQ==",
    "payment_reference_id": "external-payment-reference-1",
    "currency": "IDR",
    "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.
transaction_list	object	List of transactions. Will return empty if transaction fails. Note: in Thailand and Vietnam, the name of object `transaction_list` is returned as `transaction`.
reference_id	string	Unique identifier of payment transaction generated by merchant.
amount	int64	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. Example: Smallest amount will be 1, which represents 0.01. For currencies that do not have denomination in cents, the smallest amount will be 100, which represents 1 IDR (Rp 1) or 1 VND (₫ 1). .
create_time	uint32	Create time of the transaction.
update_time	uint32	Update time of the transaction.
transaction_sn	string	Transaction identifier in ShopeePay system.
status	uint32	Refer to Transaction Status for specific transaction statuses.
transaction_type	uint32	Refer to Transaction Types Transaction Types for specific transaction types.
merchant_ext_id	string	Unique identifier of merchant in merchant's system.
store_ext_id	string	Unique identifier of store in merchant's system.
terminal_id	string	Terminal ID refers to the Point of Sale terminal in a store.
user_id_hash	string	Used to identify the unique customer.
promo_id_applied	string	`promo_ids` applied to the payment transaction.
payment_channel	uint32	Indicates the source of fund used. Refer to Payment Channels for the respective source of fund.
co_funding	object	Will return empty if no co-funding involved. Note: This field is currently used in Thailand and Vietnam only.
promotion_ext_name	string	Name of the promotion for merchant’s reference.
redeemed_promotion_amount	int64	Amount of the promotion benefit obtained by customer through co-funding, inflated by a factor of 100. A positive integer in the smallest currency unit, with no decimal point. Note: for refund transaction types, this will be the amount of promotion benefit ShopeePay clawbacks from the customer in that refund transaction. Example: Smallest amount will be 1, which represents 0.01. For currencies that do not have denomination in cents, the smallest amount will be 100, which represents 1 IDR (Rp 1) or 1 VND (₫ 1).
redeemed_promotion_type	uint32	Refer to Promotion Types for specific transaction types.
co_funding_cost_amount	int64	Amount of cost born by merchant for the promotion benefit, inflated by a factor of 100. A positive integer in the smallest currency unit, with no decimal point. Note: for refund transaction types, this will be the amount of co-funding amount that the merchant will no longer be charged for due to that refund transaction. Example: Smallest amount will be 1, which represents 0.01. For currencies that do not have denomination in cents, the smallest amount will be 100, which represents 1 IDR (Rp 1) or 1 VND (₫ 1).

Sample API Response

RESPONSE

{
    "request_id": "input-unique-request-id-here",
    "errcode": 0,
    "debug_msg": "success",
    "transaction_list":[
        {
            "reference_id": "external-payment-reference-id",
            "amount": 10000,
            "create_time": 1647351920,
            "update_time": 1647351920,
            "transaction_sn": "019703251690639893",
            "status": 3,
            "transaction_type": 13,
            "user_id_hash": "15e455125fba426a4a2bb9145b3af2906813a7f222f6eab93b026ead62dc8d76",
            "store_ext_id": "1234"
            "promo_id_applied: "1234567890, 0987654321",
            "merchant_ext_id": "external-merchant",
            "store_ext_id": "external-store",
            "payment_reference_id": "external-payment-reference-1",
            "currency": "IDR",
            "promo_id_applied": "1234567890, 0987654321",
            "payment_channel": 1
        }
    ]
}

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
5	Transaction is in processing status, use Check Transaction Status endpoint to query the updated status of the payment
7	Expired payment code or QR
9	Customer’s account is banned
11	Duplicated request
14	Customer’s account is deleted
15	Payment amount exceeded payment limit
24	Customer's account is frozen
27	Customer's account is not activated
42	Insufficient balance
43	Insufficient balance
50	The request parameters is invalid due to payload sent is not a valid JSON
126	Customer’s transaction limit is reached
140	Customer’s wallet limit is reached
301	Invalid payment code or QR
303	Unable to make payment to own user account
603	Ineligible payment channel
604	Ineligible voucher
630	SKU ID not matched
702	Unable to redeem coins
1001	Customer is not allowed to make the transaction
1100	ShopeePay internal payment module error
1101	ShopeePay internal payment module error
1102	Customer’s SPL credit limit is reached
1104	Ineligible payment channel
1105	Transaction failed due to unsuccessful authentication
1106	Duplicated payment
1200	ShopeePay internal payment module error
1500	ShopeePay internal payment module error
1600	ShopeePay internal payment module error
1800	ShopeePay internal payment module error
1905	Expired payment code or QR
1908	Service is temporarily down for scheduled maintenance