Link & Pay

Merchant Workflow

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

Allow the user to complete account linking and store the returned access token
Optional: to retrieve coin redemption info, for displaying on the merchant checkout page
(If API-Based) Call Get Payment Methods API to retrieve the user's available payment methods for this transaction
Initiate a payment request with the Direct Payment API when the user pays

Before initiating a payment request, the merchant can call the two endpoints below based on the use cases:
- Get Payment Methods: ShopeePay will return the user's available payment methods for a given transaction, for the merchant to display for user's selection.
- Get Coin Redemption: ShopeePay will return the user's Shopee Coin redemption rules and Coin amount, should the merchant wish to display this information.
Merchant calls the Direct Payment endpoint to initiate the payment. ShopeePay will return a redirect_url for the merchant to redirect users to ShopeePay's FE should there be further payment confirmation or verification required. If the user has selected a certain payment method on the merchant's FE, merchant must inform ShopeePay of this in the request.
- For API-Based flow, if no confirmation or verification is required, ShopeePay will directly return the payment result in the Direct Payment API response. Refer to Sample API Response (When No Confirmation/Verification Needed) for this case.
ShopeePay processes the payment and returns the user back to the merchant’s page.
ShopeePay will send 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", 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.
- 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.

API Documentation

Get Payment Methods

Mandatory when the merchant maintains their own end-to-end checkout flow (API-Based flow).

Use this endpoint to fetch the user's available payment methods for the transaction. Once ShopeePay returns the information to the merchant, merchant should display each method alongside their necessary information on the merchant's FE page, for the user to select.

URL: "/v4/merchant-host/payment-methods/get"

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_idstringRequired

Echoing the request_id value from the request.

errcodeint32Required

Error code to specify the error returned. Refer to Response Code .

debug_msgstringRequired

A description of the errcode.

saved_payment_methodsarrayRequired

An array of the user's payment methods linked to ShopeePay.

Direct Payment

Use this endpoint to create a payment with an access token. If the user has selected a certain payment method on the merchant's checkout page, the payment_method_type and the payment_option_reference should be provided as the user's choice of method.

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.

amountint64Required

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.

currencystringRequired

return_urlstringConditional

payment_method_typestringConditional

payment_option_referencestringConditional

expiry_timeuint32Optional

Unix timestamp indicating when the order will expire. By default, the expiry time will be set as 30 minutes (1800 seconds), from the time the request was received. If provided, the timestamp must be no more than 30 minutes (1800 seconds) after the request time. After this time, payment attempts for the corresponding payment_reference_id will fail.

field1string

Any Payment Remark for ShopeePay Clearing Order Report. This can be a customized value for reconciliation purpose.

field2string

Any Payment Remark for ShopeePay Clearing Order Report. This can be a customized value for reconciliation purpose.

field3string

Any Payment Remark for ShopeePay Clearing Order Report. This can be a customized value for reconciliation purpose.

merchant_device_info

merchant_user_account_info

customized_partner_merchant_info

order_detail

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 (When Payment Verification is Required)

request_idstringRequired

The same value as the request_id in the request.

errcodestringRequired

Error code to specify the error returned.

debug_msgstringRequired

Debug message to provide more information.

redirect_urlstringRequired

The URL for the merchant’s FE to redirect the user to ShopeePay’s page. Note : This field will be returned when there's payment confirmation or verification required. If this is returned, the final state of the transaction will be informed via the Notify Transaction Status API. Otherwise, the state of the transaction will be reflected in the Direct Payment API response.

Response Parameters (When Payment Verification is Not Required)

request_idstringRequired

The same value as the request_id in the request.

errcodeint32Required

Error code to specify the error returned.

debug_msgstringRequired

Debug message to provide more information.

transactionobjectRequired

Will not be returned if the transaction fails.

Response Code

Value	Description
-2	A server dropped the connection
-1	A server error occurred
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
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
300088	Customer is required to complete verification
300210	ShopeePay scam warning error message