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
- 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 = "Success", the 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 24 hours.
- 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 Payment Order: Subscription
Use this endpoint to create a direct payment with an access token.
- URL: "/v3/merchant-host/transaction/payment/direct"
Request Parameters
request_idstringRequired
Unique identifier of the API request.
access_tokenstringRequired
The access token that was obtained from ShopeePay via the Get Access Token API, representing the user's authorization.
merchant_ext_idstringRequired
Unique identifier of the merchant in the merchant's system.
store_ext_idstringRequired
Unique identifier of the store in the merchant's system.
amountint64Optional
The order amount. If this parameter is provided, we will precheck the availability of each payment method using this amount. Note that the value of this parameter is inflated by 100. For example, if the currency is SGD and the amount is $12.34, set the value of this parameter to 1234. If the currency is VND and the amount is 123, set the value of this parameter to 12300.
languagestringOptional
Language in which the linked payment methods are displayed. The default is English.
Possible values:
- Indonesian :
id - English:
en - Malay:
ms - Thai:
th - Vietnamese:
vi" Potential enum: none biometric pin password pattern other Potential enum values: high, medium, low.
network_risk_info
additional_info
Additional merchant-specific information relates to device info, if any.
merchant_user_account_infojson string
customized_partner_merchant_infojson string
order_detailjson string
payment_initiationstring
Indicates how the payment is initiated.
Potential value:
- MERCHANT_QR_PROPRIETARY: Merchant-presented proprietary QR scanned by the customer to initiate payment.
- MERCHANT_QR_NATIONAL: Merchant-presented national / standardized QR scanned by the customer to initiate payment.
- CUSTOMER_QR_PROPRIETARY: Customer-presented proprietary QR scanned by the merchant to initiate payment.
- CUSTOMER_QR_NATIONAL: Customer-presented national / standardized QR scanned by the merchant to initiate payment.
- ONLINE_CHECKOUT: Online checkout where the customer confirms an order and pays with a non-QR method (card, wallet, giro, etc.).
- SUBSCRIPTION: Recurring or scheduled billing initiated automatically.
- TRANSFER: Fund transfer between accounts (for example, P2P or internal balance movement) without an order/cart.
The following scenarios define which risk field the merchant should provide to SPP:
| Payment Initiation Scenario | Description | API Fields |
|---|---|---|
| SETTLEMENT | field1, field2, field3 | |
| MERCHANT_QR_PROPRIETARY | Merchant-presented proprietary QR scanned by the customer to initiate payment. | Device Info, User Account, Merchant Account, Order Details |
| MERCHANT_QR_NATIONAL | Merchant-presented national QR scanned by the customer to initiate payment. | Device Info, User Account, Merchant Account, Order Details, QR Details (If Merchant who handles QR reading) |
| CUSTOMER_QR_PROPRIETARY | Customer-presented proprietary QR scanned by the merchant to initiate payment. | Device Info, User Account, Merchant Account, Order Details |
| CUSTOMER_QR_NATIONAL | Customer-presented national / standardized QR scanned by the merchant to initiate payment. | Device Info, User Account, Merchant Account, Order Details, QR Details (If Merchant who handles QR reading) |
| ONLINE_CHECKOUT | Online checkout where the customer confirms an order and pays the non-QR method transaction. | Device Info, User Account, Merchant Account, Order Details, Items |
Response Parameters
request_idstring
The same value as the request_id in the request.
errcodeint32
Error code to specify the error returned.
debug_msgstring
Debug message to provide more information.
transactionobject
Will not be returned if the transaction fails.
Response Code
| Value | Description |
|---|---|
| -2 | A server dropped the connection |
| -1 | A server error occurredPlease 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 |
| 9 | Customer’s account is banned |
| 11 | Duplicated request |
| 14 | Customer’s account is deleted |
| 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 |
| 105 | Invalid auth code |
| 140 | Customer’s wallet limit is reached |
| 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 |
| 1103 | Customer is required to link their bank account |
| 1104 | Ineligible payment channel |
| 1105 | Transaction failed due to unsuccessful authentication |
| 1106 | Duplicated payment |
| 1200 | ShopeePay internal payment module error |
| 1201 | ShopeePay internal payment module error |
| 1500 | ShopeePay internal payment module error |
| 1800 | ShopeePay internal payment module error |
| 1801 | ShopeePay internal payment module error |
| 1906 | Unable to process refund due to transaction has been failed |
| 1907 | Ineligible payment channel |
| 1908 | Service is temporarily down for scheduled maintenance |
| 1601 | Error due to invalid promotion |