Checkout With ShopeePay

Merchant Workflow

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

Initiate a payment request when customer selects to pay
Handle the redirect URL returned
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:

Customer selects goods or services and proceeds to check out from the merchant's application or website using ShopeePay. Merchant sends payment request to ShopeePay server via the Create Checkout Order endpoint. ShopeePay returns redirectUrl and this URL can be used to direct users to Shopee/ShopeePay application or website.
Customer is redirected to either Shopee/ShopeePay application or website to proceed with payment.
Customer sees the payment details such as payment amount, supported payment methods, and relevant promotional information on the Shopee/ShopeePay application or website.
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.
Customer is then redirected back to the merchant's page to view payment status, as specified by the merchant in the urlParam.url of the Create Checkout Order endpoint.
- Note: Redirection to urlParams.url 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.
Merchants must call the Check Transaction Status endpoint to query the status of the transaction.
- If the response code is "Success" and the latestTransactionStatus is 00, 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 until payment expires. 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 until the payment expires.

Create Checkout Order

Use this endpoint to create a pending order to be paid by ShopeePay.
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	54
Path	.../v1.0.2/debit/payment-host-to-host
Version	v1.0.2

Request Parameters

Field	Type	Mandatory	Description
partnerReferenceNo	String	M	Unique identifier for request. Accepts up to 64 characters.
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 transaction 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.
urlParams	Array of Object	M
url	String	M	Indicates 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.
type	String	M	Indicates the type of the sent url. Only accepts PAY_RETURN value.
isDeepLink	String	M	Indicates whether the url is a deep link or not. Only accepts either ‘Y’ or ‘N’ value.
validUpTo	String	O	By default, the expiry time will be set to 1200 seconds (20 minutes), from the time the request was received. Accepts up to 432,000 seconds (5 days), from the time request was received If this field is filled, `partnerReferenceNo` in this request will expire after the specified time period (in seconds) and payment attempt to this `partnerReferenceNo` will fail. Using ISO 8601 timestamp format.
pointOfInitiation	String	M	Type of the merchant's platform that the customer triggered the checkout flow from. Accepted values: "app" "pc" "mweb" (mobile web)
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.
phone	String	O	Registered 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.
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}\”}
preferredPaymentMethodType	String	O	Allow merchants to set a preferred payment method for the payment order, which will be pre-selected on the customer's payment page. Customer will still have the option to view and choose from other available payment methods Accepted value: `SPayLater` = 'spay_later'

Sample API Request

REQUEST

{
   "partnerReferenceNo": "Testing-123",
   "amount": {
      "value": "10000.00",
      "currency": "IDR"
   },
   "merchantId": "Merchant123",
   "externalStoreId": "Store123",
   "urlParams": [
      {
         "url": "https://www.test.com",
         "type": "PAY_RETURN",
         "isDeepLink": "N"
      }
   ],
   "validUpTo": "2022-07-20T07:00:00+07:00",
   "pointOfInitiation": "app",
   "additionalInfo": {
      "promoIds": "Promo1, Promo2",
      "metadata": "{\"field1\":\"Data1\",\"field2\":\"Data2\",\"field3\":\"Data3\"}"
   }
}

Copy

Respond 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.
webRedirectUrl	String	M	Indicates the universal URL to ShopeePay's payment page. Merchant should not impose any kind of restrictions for this URL, such as: Whitelisting only specific domains Restricting specific IPs Limiting URL length The maximum length for the webRedirectUrl parameter is 2048 chars

Sample API Response

RESPONSE

{
   "responseCode": "2005400",
   "responseMessage": "Successful",
   "referenceNo": "169940762961566068",
   "webRedirectUrl": "https://id.uat.shp.ee/shopeepay_checkout_id?type=start&mid=10202124&medium_index=dFhkbmR1bTBIamhW5ALIHEvw_6Ka2b4jCx031mB9F0VbIxfnE82M_1KXVjVfK5wpa-p2pQ& order_key=zPQK1kiWWbAD14jtiLE4hB71j3NTZIlr_RqewrLbDVrwBexbwrVmhdgFYCrkFP3IRkrt4-3hg0loMg&order_sn=169940762961566068&return_url=aHR0cHM6Ly93d3cuZ29vZ2xlLmNvbS8%2FYW1vdW50PTE3MDAwJmNsaWVudF9pZD1PcGVuKOFQSStUZXN0aW5nKOFjY291bnQILSs1JnJlZmVyZW5jZV9pZD1GMDNCNTJmNzEXNEU5R2ZmMEM3Rkc00TQmcmVzdWx0X2NvZGU9MjAz JnNpZ25hdHVyZT1LWF9sa3NBOTJRm5qNmlvY1h4bVNTQ1daMEdPam5DRVRWCXNTYmJKWkt3JTNE&source=web&token=dFhkbmR1bTBIamhW5ALIHEvw_6Ka2b4jCx031mB9F0VbIxfnE82M_1KXVjVfK5wpa-p2pQ"
}

Copy

Respond 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	54	00	2005400	Successful	Mark CWS(Checkout With Shopeepay) generate process to Success. Forward customer to Shopeepay page
400	54	00	4005400	Bad Request	Mark CWS generate process to Failed. Retry request with proper parameter
400	54	01	4005401	Invalid field format {fieldName} Invalid field format {timestamp} Invalid Field Format {validUpTo} Invalid Field Format {promoIds} Invalid Field Format {paymentChannelId} Invalid Field Format {paymentChannelName} Invalid Field Format {paymentMethodName} Invalid Field Format {fraudCheckInfo} Invalid field format {currency} 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 Field Format	Mark CWS generate process to Failed. Retry request with proper parameter
400	54	02	4005402	Invalid mandatory field {fieldName} Invalid mandatory field {originalPartnerReferenceNo} Invalid mandatory field {merchantId}. Exceed maximum character length Invalid mandatory field {externalStoreId}. Exceed maximum character length Invalid Mandatory Field {currency} Invalid Mandatory Field {merchantId} Invalid Mandatory Field {pointOfInitiation} Invalid Mandatory Field {externalStoreId} Invalid Mandatory Field {pointOfInitiation} or {accountToken} Invalid Mandatory Field {value}. Non Positive Amount Is Not Allowed Invalid Mandatory Field + {error message}	Mark CWS generate process to Failed. Retry request with proper parameter
401	54	00	4015400	Unauthorized. Invalid Client Key Unauthorized.{error message}	Mark CWS generate process to Failed. Retry request with proper parameter
401	54	01	4015401	Invalid Token	Mark CWS generate process to Failed. Retry request with proper parameter
403	54	01	4035401	Feature Not Allowed Feature Not Allowed. Selected Payment Channel Is Disabled For Merchant	Mark CWS generate process to Failed. Retry request periodically or consult to Shopeepay
403	54	06	4035406	Feature Not Allowed. Service Is Temporarily Down For Scheduled Maintenance	Mark CWS generate process to Failed. Retry request periodically or consult to Shopeepay
404	54	08	4045408	Invalid merchant, status is not active Invalid Field Format	Mark CWS generate process to Failed. Retry request with proper parameter or Contact Shopeepay to check merchant/store status
404	54	13	4045413	Invalid Amount. Currency Does Not Support Cents	Mark CWS generate process to Failed. Retry request with proper parameter
404	54	18	4045418	Inconsistent Request	Mark CWS generate process to Failed. Retry request with proper parameter
409	54	00	4095400	Conflict	Mark CWS generate process to Failed. Retry request periodically or consult to Shopeepay
500	54	00	5005400	General Error	Mark CWS generate process to Failed. Retry request periodically or consult to Shopeepay
500	54	01	5005401	Internal Server Error	Mark CWS generate process to Failed. Retry request periodically or consult to Shopeepay
504	54	00	5045400	Timeout	Mark CWS generate process to Failed. Retry request periodically or consult to Shopeepay

Invalidate Order

Use this endpoint to invalidate the existing order using payment reference id for Checkout with ShopeePay if the order in the merchant’s system is closed/cancelled. Once the order payment reference id is invalidated successfully, the corresponding webRedirectUrl can no longer be used to make payment.
All API requests require a header. Refer to API Param Specification → Transaction Request

Specification

The following table is the specification of the API:

HTTP Method	POST
Service Code	57
Path	.../v1.0/debit/cancel
Version	v1.0

Request Parameter

Field	Type	Mandatory	Description
originalPartnerReferenceNo	String	M	Unique identifier of the transaction that the merchant intends to invalidate or cancel.
merchantId	String	M	Unique identifier of merchant in merchant system. Accept up to 64 characters.
externalStoreId	String	M	Unique identifier of store in merchant system. Accept up to 64 characters.

Sample API Request

REQUEST

{
   "originalPartnerReferenceNo": "Testing-123",
   "merchantId": "Merchant123",
   "externalStoreId": "Store123"
}

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.
cancelTime	String	C	Update time of the individual transaction. The value will be returned for successful invalidate request. Using ISO-8601 timestamp format.
originalReferenceNo	String	C	Transaction identifier in ShopeePay system that is shown to the customer. The value will be returned for successful payment.

Sample API Response

RESPONSE

{
   "responseCode": "2005700",
   "responseMessage": "Successful",
   "cancelTime": "2024-07-03T16:41:41+07:00",
   "originalReferenceNo": "123323887564698876"
}

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	57	00	2005700	Successful	Mark CWS(Checkout With Shopeepay) cancel process to Success. Mark CWS payment to Failed
400	57	00	4005700	Bad Request	Mark CWS cancel process to Failed. Retry request with proper parameter
400	57	01	4005701	Invalid Field Format	Mark CWS cancel process to Failed. Retry request with proper parameter
400	57	02	4005702	Invalid mandatory field {merchantId}. Exceed maximum character length Invalid mandatory field {externalStoreId}. Exceed maximum character length Invalid mandatory field {originalPartnerReferenceNo} Invalid mandatory field {externalStoreId} Invalid Mandatory Field + {error message}	Mark CWS cancel process to Failed. Retry request with proper parameter
401	57	00	4015700	Unauthorized. Invalid Client Key Unauthorized.{error message}	Mark CWS cancel process to Failed. Retry request with proper parameter
401	57	01	4015701	Invalid Token	Mark CWS cancel process to Failed. Retry request with proper parameter
403	57	01	4035701	Feature Not Allowed	Mark CWS cancel process to Failed. Contact Shopeepay to check merchant/store supported product flow
403	57	15	4035715	Transaction Not Permitted. Transaction Already In Final State Transaction Not Permitted. Merchant Info Mismatch Transaction Not Permitted. Order Is Already Expired	Mark CWS cancel process to Failed. Retry request with proper parameter or retry request "Check Debit Status" to get final status
404	57	01	4045701	Transaction Not Found	Mark CWS cancel process to Failed. Retry request with proper parameter
404	57	08	4045708	Invalid Merchant Invalid Store Invalid fieldName	Mark CWS cancel process to Failed. Contact Shopeepay to check merchant/store status
409	57	00	4095700	Conflict	Mark CWS cancel process to Failed. Retry request periodically or consult to Shopeepay
500	57	00	5005700	General Error	Mark CWS cancel process to Failed. Retry request periodically or consult to Shopeepay
500	57	01	5005701	Internal Server Error	Mark CWS cancel process to Failed. Retry request periodically or consult to Shopeepay
504	57	00	5045700	Timeout	Mark CWS cancel process to Failed. Retry request periodically or consult to Shopeepay

Check Checkout Transaction Status

Use this endpoint to query the status of a Checkout with ShopeePay transaction.
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 latestTransctionStatus field in the API response. This will provide the most up-to-date information.

Specification

The following table is the specification of the API:

HTTP Method	POST
Service Code	55
Path	.../v1.0/debit/status
Version	v1.0

Request Parameter

Field	Type	Mandatory	Description
originalPartnerReferenceNo	String	M	Unique identifier of the transaction merchant would like to query, which could be `partnerReferenceNo` or `partnerRefundNo`.
merchantId	String	M	Unique identifier of merchant in merchant system.
externalStoreId	String	M	Unique identifier of store in merchant system.
serviceCode	String	M	Service code of original transaction, which could be 54 (Link and Pay transaction) or 58 (refund).
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 refund amount. Accepted values: IDR

Sample API Request

REQUEST

{
   "originalPartnerReferenceNo": "Testing-123",
   "merchantId": "Merchant123",
   "externalStoreId": "Store123",
   "serviceCode": "54",
   "amount": {
      "value": "10000.00",
      "currency": "IDR"
   }
}

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
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.
serviceCode	String	M	Service code of original transaction, which could be 54 (create CwS transaction) or 58 (refund).
latestTransactionStatus	String	M	Refer to Transaction Status for specific transaction statuses
transAmount	Object	O
value	String	M	Transaction amount. Sample: 10.000,00 will be placed with 10000.00
currency	String	M	Refers to the currency abbreviation for the transaction. IDR
paidTime	String	M	Update time of the individual transaction. Using ISO-8601 timestamp format.
additionalInfo	Object	O
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
merchantId	String	O	Unique identifier of merchant in merchant system.
externalStoreId	String	O	Unique identifier of store in merchant system.
userIdHash	String	O	Unique identifier of the user making the payment.
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": "2005500",
   "responseMessage": "Successful",
   "original ReferenceNo": "Testing-123",
   "originalPartnerReferenceNo": "Payment-123",
   "serviceCode": "54",
   "latestTransactionStatus": "00",
   "paidTime": "2022-07-20T07:10:10+07:00",
   "transAmount": {
      "value": "10000.00",
      "currency": "IDR"
   },
   "additionalInfo": {
      "createTime": "2022-07-20T07:05:00+07:00",
      "productType": 16,
      "transactionType": 13,
      "userIdHash": "15e455125fba426a4a2bb9145b3af2906813a7f222f6eab93b026ead62dc8d76",
      "merchantId": "Merchant123",
      "externalStoreId": "Store123",
      "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	55	00	2005500	Successful	Mark CWS payment to corresponding status according to response.additionalInfo.latestTransactionStatus. Retry request periodically if didn't get final status
400	55	00	4005500	Bad Request	Mark CWS payment to Pending. Retry request with proper parameter
400	55	01	4005501	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 CWS payment to Pending. Retry request with proper parameter
400	55	02	4005502	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 CWS payment to Pending. Retry request with proper parameter
400	55	08	4005508	Invalid Field format Invalid Merchant	Mark CWS payment to Pending. Retry request periodically or consult to Shopeepay
401	55	00	4015500	Unauthorized invalid client key Unauthorized.{error message}	Mark CWS payment to Pending. Retry request with proper parameter
401	55	01	4015501	Invalid Token	Mark CWS payment to Pending. Retry request with proper parameter
403	55	08	4035508	Invalid Merchant, Status Is Not Active Invalid Store, Status Is Not Active	Mark CWS payment to Pending. Contact Shopeepay to check merchant/store status
404	55	01	4045501	Transaction not found	Mark CWS payment to Failed
404	55	08	4045508	Entity not found	Mark CWS payment to Pending. Retry request periodically or consult to Shopeepay
404	55	13	4045513	Invalid amount. Mismatch with original transaction Invalid Amount. Non Positive Amount Is Not Allowed	Mark CWS payment to Pending. Retry request with proper parameter
409	55	00	4095500	Conflict	Mark CWS payment to Pending. Retry request periodically or consult to Shopeepay
500	55	00	5005500	General Error	Mark CWS payment to Pending. Retry request periodically or consult to Shopeepay
500	55	01	5005501	Internal Server Error	Mark CWS payment to Pending. Retry request periodically or consult to Shopeepay
504	55	00	5045500	Timeout	Mark CWS 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	58
Path	.../v1.0/debit/refund
Version	v1.0

Refer to Refund Payment for 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 /debit/payment-host-to-host request before considering the payment successful.

HTTP Method	POST
Service Code	56
Path	.../v1.0/debit/notify
Version	v1.0

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

Checkout With ShopeePay

Merchant Workflow

Create Checkout Order

Specification

Request Parameters

Sample API Request

REQUEST

Respond Parameter

Sample API Response

RESPONSE

Respond Code

Invalidate Order

Specification

Request Parameter

Sample API Request

REQUEST

Response Parameter

Sample API Response

RESPONSE

Response Code

Check Checkout Transaction Status

Specification

Request Parameter

Sample API Request

REQUEST

Response Parameter

Sample API Response

RESPONSE

Response Codes

Refund Payment

Notify Transaction Status

On this page