Subscription

Merchant Workflow

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

Completed account linking request and store returned access token
Initiate a payment request for Subscription when payment is due

The following figure illustrates the workflow of accepting a payment in the Subscription payment scenario:

Merchant calls Create Payment Order: Subscription endpoint to charge from the customer’s ShopeePay account.
ShopeePay will conduct a sequential attempt with each of the customer’s linked payment methods with ShopeePay, until the transaction is successful.
ShopeePay will sends an asynchronous message via Notify Transaction Status endpoint to inform merchants on the payment result.
Merchant can also 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 = "Failed", the 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 30 minutes
- 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 30 minutes.

Create Payment Order: Subscription

Use this endpoint to create a direct payment with an access token.
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	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 of payment transaction generated by merchant.
merchantId	String	M	Unique identifier of merchant in merchant system. Accepts up to 64 characters.
externalStoreId	String	M	Unique identifier of store in merchant system. 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 payment amount. Accepted values: IDR
urlParams	Array of Object	M	Array of object
url	String	M	Indicates the URL of the merchant's platform to return back to, once the payment on ShopeePay’s page is completed.
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.
additionalInfo	Object	O
accountToken	String	M	The `accountToken` used to represent the account binding between Merchant's platform and ShopeePay.
useCoin	Boolean	O	Use this field to indicate whether the customer prefers to use or not to use coins to offset their payment on the merchant’s platform. The default value is set to false. True: attempt to use coins False: do not use coins
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. 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": "Direct Payment-123",
  "merchantId": "Merchant123",
  "externalStoreId": "Store123",
  "amount": {
    "value": "10000.00",
    "currency": "IDR"
  },
  "urlParams": [
    {
      "url": "https://www.test.com",
      "type": "PAY_RETURN",
      "isDeepLink": "N"
    }
  ],
  "additionalInfo": {
    "useCoin": true,
    "accountToken": "+Tgd0x95GGgt3kN7m1ItWDGqCTAVYysV",
    "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
partnerReferenceNo	String	O	Unique identifier of payment transaction generated by merchant
ReferenceNo	String	C	Transaction Identifier in ShopeePay System
additionalInfo	Object	O
value	String	O	Transaction amount. Sample: 10.000,00 will be placed with 10000.00
merchantId	String	O	Unique identifier of merchant in merchant system
externalStoreId	String	O	Unique identifier of store in merchant system
createTime	String	O	Create time of the individual transaction.
updateTime	String	O	Update time of the individual transaction.
latestTransactionStatus	String	O	Refer to Transaction Status for specific transaction statuses
transactionType	uint32	O	13, referring to subscription transaction type. Refer to Transaction Types for specific transaction types
userIdHash	String	O	Identifier for customer that made the payment.
promoIdApplied	String	O	Comma separated eligible promoIds of 100 characters or less (up to 20), if any.
paymentChannel	int32	O	Indicates the source of fund used. Refer to Payment Channels for the respective source of fund.

Sample API Response

JS EXAMPLE

{
   "responseCode": "2005400",
   "responseMessage": "Successful",
   "partnerReferenceNo": "Direct Payment-123",
   "referenceNo": "Shopee Pay-Direct Payment-123",
   "additionalInfo": {
      "value": "10000.00",
      "merchantId": "Merchant123",
      "externalStoreId": "Store123",
      "createTime": "2022-07-20T07:00:00+07:00",
      "updateTime": "2022-07-20T07:00:01+07:00",
      "transactionType": 13,
      "userIdHash": "15e455125fba426a4a2bb9145b3af2906813a7f222f6eab93b026ead62dc8d76",
      "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	54	00	2005400	Successful	Mark Subscription process to Success. Forward customer to Shopeepay page
400	54	00	4005400	Bad Request	Mark Subscription 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 Subscription 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 Subscription process to Failed. Retry request with proper parameter
401	54	00	4015400	Unauthorized. Invalid Client Key Unauthorized.{error message}	Mark Subscription process to Failed. Retry request with proper parameter
401	54	01	4015401	Invalid Token	Mark Subscription 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 Subscription 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 Subscription process to Failed. Retry request periodically or consult to Shopeepay
404	54	08	4045408	Invalid merchant, status is not active Invalid Field Format	Mark Subscription 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 Subscription process to Failed. Retry request with proper parameter
404	54	18	4045418	Inconsistent Request	Mark Subscription process to Failed. Retry request with proper parameter
409	54	00	4095400	Conflict	Mark Subscription process to Failed. Retry request periodically or consult to Shopeepay
500	54	00	5005400	General Error	Mark Subscription process to Failed. Retry request periodically or consult to Shopeepay
500	54	01	5005401	Internal Server Error	Mark Subscription process to Failed. Retry request periodically or consult to Shopeepay
504	54	00	5045400	Timeout	Mark Subscription process to Failed. Retry request periodically or consult to Shopeepay

Check Transaction Status for Subscription

Use this endpoint to query the status of Subscription 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 (Subscription) 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

RESPONSE

{
   "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 subscription transaction) or 58 (refund).
latestTransactionStatus	String	M	Refer to Transaction Status for specific transaction statuses
transAmount	Object	O
value		C	Transaction amount. Sample: 10.000,00 will be placed with 10000.00
currency		C	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 Subscription 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 Subscription 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 Subscription payment to Pending. Retry request with proper parameter
400	55	01	4005501	Invalid Field Format	Mark Subscription 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 Subscription payment to Pending. Retry request with proper parameter
400	55	08	4005508	Invalid Field format Invalid Merchant	Mark Subscription payment to Pending. Retry request periodically or consult to Shopeepay
401	55	00	4015500	Unauthorized invalid client key Unauthorized.{error message}	Mark Subscription payment to Pending. Retry request with proper parameter
401	55	01	4015501	Invalid Token	Mark Subscription 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 Subscription payment to Pending. Contact Shopeepay to check merchant/store status
404	55	01	4045501	Transaction not found	Mark Subscription payment to Failed
404	55	08	4045508	Entity not found	Mark Subscription 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 Subscription payment to Pending. Retry request with proper parameter
409	55	00	4095500	Conflict	Mark Subscription payment to Pending. Retry request periodically or consult to Shopeepay
500	55	00	5005500	General Error	Mark Subscription payment to Pending. Retry request periodically or consult to Shopeepay
500	55	01	5005501	Internal Server Error	Mark Subscription payment to Pending. Retry request periodically or consult to Shopeepay
504	55	00	5045500	Timeout	Mark Subscription 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 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 /debit/payment-host-to-host request before considering the payment successful.

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

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

Subscription

Merchant Workflow

Create Payment Order: Subscription

Specification

Request Parameters

Sample API Request

REQUEST

Response Parameter

Sample API Response

JS EXAMPLE

Response Codes

Check Transaction Status for Subscription

Specification

Request Parameter

Sample API Request

RESPONSE

Response Parameter

Sample API Response

RESPONSE

Response Codes

Refund Payment

Notify Transaction Status

On this page