Checkout With ShopeePay

Merchant Workflow

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

  1. Initiate a payment request when customer selects to pay

  2. Handle the redirect URL returned

  3. Handle notification callback or query to check payment results

The following figure illustrates the workflow of accepting a payment in the Checkout with ShopeePay payment scenario:

  1. Customer selects goods or services and proceeds to check out from the merchant's application or website. Merchant sends payment request to ShopeePay server via the Create Checkout Order endpoint. ShopeePay returns redirect_url_http and this URL can be used to direct users to Shopee/ShopeePay application or website.
  2. Customer is redirected to either Shopee/ShopeePay application or website to proceed with payment.
  3. Customer sees the payment details such as payment amount, supported payment methods, and relevant promotional information on the Shopee/ShopeePay application or website.
  4. ShopeePay system returns the transaction result to the merchant. Meanwhile, customers will also see the updated payment result on the Shopee/ShopeePay application or website. ShopeePay also sends an asynchronous message via Notify Transaction Status endpoint to inform merchants on the payment result.
  5. Customer is then redirected back to the merchant's page to view payment status, as specified by the merchant in the redirect_url of the Create Checkout Order endpoint. Note: Redirect to return_url_http should never be used as an indication of payment success. The Merchant should only rely on the server request response to check the final status of payment.
  6. 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 Checkout Order

Use this endpoint to create a pending order to be paid by ShopeePay.

  • URL: "/v3/merchant-host/order/create"

Request Parameters

FieldTypeMandatoryDescription
request_idstringYUnique identifier for request, accepts up to 64 characters.
payment_reference_idstringYUnique identifier of transaction generated by merchant.
merchant_ext_idstringYUnique identifier of merchant in merchant’s system.
store_ext_idstringYUnique identifier of store in merchant’s system.
amountint64YAmount used for the payment, 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).
currencystringYCurrency 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.
return_urlstringYIndicates the URL (in HTTP links or URL scheme formats) of the merchant’s application to redirect back to once the payment is processed by ShopeePay or when the customer canceled the payment.
platform_typestringYType of the merchant’s platform that the customer triggered the checkout flow from.
Accepted values:
“app”
“pc”
“mweb” (mobile web)
validity_perioduint32NBy default, the expiry time will be set to 1200 seconds (20 minutes), from the time the request was received.
If this field is filled, the order with the corresponding payment_reference_id in this request will expire after the specified time period (in seconds) and payment attempts to this payment_reference_id will fail.
Accepts up to:
3600 seconds (60 minutes) in Malaysia, Philippines and Singapore
172800 seconds (2 days) for Vietnam
432000 seconds (5 days) for Indonesia and Thailand
Note: The system will return an error if both validity_period and expiry_time parameters are used simultaneously.
expiry_timeuint32NUnix timestamp.
By default, the expiry time will be set to 1200 seconds (20 minutes), from the time the request was received.
If this field is filled, the order with the corresponding payment_reference_id in this request will expire after the specified timestamp and payment attempts to this payment_reference_id will fail.
Accepts up to:
3600 seconds (60 minutes) in Malaysia, Philippines and Singapore
172800 seconds (2 days) for Vietnam
432000 seconds (5 days) for Indonesia and Thailand
Note: The system will return an error if both validity_period and expiry_time parameters are used simultaneously.
promo_idsstringNComma 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_infostringNAdditional 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}"}
phonestringNRegistered phone number of the customer on merchant’s platform, to be provided with the country code and without the plus sign.
Example:
An Indonesian phone number “82112345678” should be passed in as “6282112345678”, with 62 being the country code.
A Vietnamese phone number “0981234567” should be passed in as “84981234567”, with 84 being the country code.
preferred_payment_method_typestringNAllow merchants to choose the preferred payment method for the payment order, where this payment method will be selected at customer's payment page.
Accepted value:
SPayLater = 'spay_later'

Sample API Request

REQUEST

{
"request_id": "input-unique-request-id-here",
"payment_reference_id": "ref-must-be-unique",
"merchant_ext_id": "external-merchant",
"store_ext_id": "external-store",
"amount": 10000,
"currency": "IDR",
"return_url": "www.shopeepay.com",
"platform_type": "app",
"validity_period": 3600,
"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.
redirect_url_httstringIndicates the universal URL to ShopeePay's payment page. Merchant should not impose any domain whitelisting and IP restriction for this URL.

Sample API Response

RESPONSE

{
"request_id": "input-unique-request-id-here",
"errcode": 0,
"debug_msg": "success",
"redirect_url_http": "https://id.shp.ee/sppay_checkout_id?type=start&mid=10037747&target_app=shopee&medium_index=dFhkbmR1bTBIamhW1leIKk_wafo0ImuIpeW6op9elv5oSw&order_key=GD92qfhlclES7vmlD7plyHQGdRt9mNevhPFE8Gu9IWXcoFhiQNSDOxOcUSnLniuPkheNSp6fPcZ9bw&return_url=aHR0cHM6Ly93d3cuZ29vZ2xlLmNvbS5zZy8%2FYW1vdW50PTUwMDAwJmNsaWVudF9pZD10ZXN0eXkraG9zdCZyZWZlcmVuY2VfaWQ9dGVzdDEyJnJlc3VsdF9jb2RlPTIwMyZzaWduYXR1cmU9dnZ3dk1Mb1JBYlpYN2pMdjJiR2JJcDFMQVBZOFZ0Sjk5ZFdIUmhuMHhDZyUzRA%3D%3D&source=web&token=dFhkbmR1bTBIamhW1leIKk_wafo0ImuIpeW6op9elv5oSw"
}
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