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.
Please contact ShopeePay for details of this API.
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
| Field | Type | Mandatory | Description |
|---|---|---|---|
| request_id | string | Y | Unique identifier for each request, accepts up to 64 characters. |
| payment_reference_id | string | Y | Unique identifier of payment transaction generated by merchant. |
| merchant_ext_id | string | Y | Unique identifier of merchant in merchant's system. |
| store_ext_id | string | Y | Unique identifier of store in merchant's system. |
| access_token | string | Y | The access token obtained from ShopeePay via the Get Access Token when the customer linked their account. |
| amount | int64 | Y | Amount used for the payment, inflated by a factor of 100. A positive integer in the smallest currency unit, with no decimal point. |
| currency | string | Y | Currency that is associated with the payment amount. |
| return_url | string | Y | The URL for the merchant's platform to return back to, once the payment on ShopeePay’s page is completed. |
| payment_method_type | string | C | Indicates the type of payment method used. Refer to Payment Method Type. Note: This field is mandatory only for the Link & Pay (API-Based) product flow. |
| payment_option_reference | string | C | A unique identifier to represent the user's choice of method, obtained from the Get Payment Methods response. Note: This field is mandatory only for the Link & Pay (API-Based) product flow. |
| promo_ids | string | N | Comma separated eligible promo_ids of 100 characters or less (up to 20), if any. |
| additional_info | string | N | Additional information will be in json format. |
| expiry_time | uint32 | N | Unix timestamp. Max allowed value is 30 mins. |
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","access_token": "uXjWuhPGepSOtntoC8kTK5er6DlbUiGeSJDt53","amount": 1000000,"currency": "IDR","use_coin": true,"return_url": "https://isv-domain.com","expiry_time": 1716193900}
Copy
Response Parameters (When Payment Verification is Required)
| Field | Type | Description |
|---|---|---|
| request_id | string | The same value as the request_id in the request. |
| errcode | string | Error code to specify the error returned. |
| debug_msg | string | Debug message to provide more information. |
| redirect_url | string | 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. |
Sample API Response (When Payment Verification is Required)
RESPONSE
{"request_id": "input-unique-request-id-here","errcode": 0,"debug_msg": "success","redirect_url": "https://uat.shopeepay.co.id/s/browser/payment/auth/passcode-verify?mode=fullscreen&next=https%3A%2F%2Fuat.shopee.vn%2Fs%2Fbrowser%2Fpayment%2Fauth%2FtokenizedPaymentResult%3Freturn_url%3Dhttps%253A%252F%252Fgoogle.com%26ticket%3DbxfWQkI0VfGzlj7ANMudkMYO9RvkO1PM&return_url=https%3A%2F%2Fuat.shopee.vn%2Fs%2Fbrowser%2Fpayment%2Fauth%2FtokenizedPaymentResult%3Fresult%3D201%26return_url%3Dhttps%253A%252F%252Fgoogle.com%26ticket%3DbxfWQkI0VfGzlj7ANMudkMYO9RvkO1PM&scenario=7cdccb66-cd7a-448f-a01f-b2ddd8970e53&source=TokenizedPayment&ticket=bxfWQkI0VfGzlj7ANMudkMYO9RvkO1PM"}
Copy
Response Parameters (When Payment Verification is Not Required)
| Field | Type | Description |
|---|---|---|
| request_id | string | The same value as the request_id in the request. |
| errcode | int32 | Error code to specify the error returned. |
| debug_msg | string | Debug message to provide more information. |
| transaction | object | Will not be returned if the transaction fails. |
| * reference_id | string | Unique identifier of payment transaction generated by merchant.Same value as the payment_reference_id in the request. |
| * amount | int64 | Amount 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). |
| * status | uint32 | Refer to Transaction Status for specific transaction statuses. |
| * transaction_type | uint32 | 13, referring to subscription transaction type.Refer to Transaction Types for specific transaction types. |
| * transaction_sn | string | Transaction identifier in ShopeePay's system. |
| * create_time | uint32 | Create time of the transaction. |
| * update_time | uint32 | Update time of the transaction. |
| * user_id_hash | string | Identifier for the customer that made the payment. |
| * merchant_ext_id | string | Unique identifier of merchant in merchant's system. |
| * store_ext_id | string | Unique identifier of store in merchant's system. |
| * promo_id_applied | string | promo_ids applied to the payment transaction. |
| * payment_channel | uint32 | Indicates the source of funds used. Refer to Payment Channels for the respective source of fund. |
| *payment_method_type | string | Indicates payment method that being used for payment (eg. ewallet/ giro_bank/card). Refer to payment_method_type. |
Sample API Response (When Payment Verification is Not Required)
JS EXAMPLE
{"request_id": "input-unique-request-id-here","errcode": 0,"debug_msg": "success","transaction": {"reference_id": "input-payment-ref-id","amount": 1000000,"create_time": 1716193693,"update_time": 1716193693,"transaction_sn": "4737856404311306","status": 3,"transaction_type": 13,"merchant_ext_id": "external-merchant","store_ext_id": "external-store","user_id_hash": "697863f9295aeddcb3db598ecbc74c59a13335abf4d8c41b40e33b28a9d7d63c","payment_channel": 1,"payment_method_type": "ewallet"}}
Copy
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 |