Account Linking
ShopeePay offers the following functionalities for account linking and payment use cases:
- Initiate an Account Linking & Get Account Token
- Request for Account Unlinking
- Use Cases for Account Linking
Merchant Workflow
To accept the payment in this scenario, the merchant needs to complete the following steps
Initiate Get Auth Code when customer chooses to link their ShopeePay account.
Bring the user to SPP's frontend to complete the authorization
Get access token by using returned partnerReferenceNo, and save token for future use cases (e.g. to obtain user information).
Initiate a payment request (via Link & Pay, Subscription, and Authorization & Capture) when customer selects to pay or when payment is due.
- After customer chooses to link their ShopeePay account on merchant's application or website, the merchant calls the Get Auth Code endpoint to start the linking process.
- ShopeePay returns an
authCode
which should be appended to the provided static URL, allowing merchants to direct users to ShopeePay's linking agreement page. - The customer agrees to link their account to the merchant.
- Upon successful linking, the customer returns back to the merchant’s page as indicated in the
redirectUrl
in the Account Linking request, along with anauthCode
,partnerReferenceNo
. - Merchant can reply on the
authCode
orpartnerReferenceNo
passed by its frontend, to call the /registration-account binding endpoint - Once the merchant obtains the account token, they should save it securely for future use.
- Should the customer choose to unlink ShopeePay in the future, the merchant should call the Account Unlink endpoint to invalidate the access token. Once the unlink request is successful, the merchant will not be able to get information or charge the customer’s ShopeePay account.
Initiate Account Linking
- Use this endpoint to initiate the account linking process of a ShopeePay account to your platform.
- All API requests require a header. Refer to API Param Specification → Transaction Request
Specification
The following table is specification of this API:
HTTP Method | GET |
---|---|
Service Code | 10 |
Path | .../v1.0/get-auth-code |
Version | v1.0 |
Request Parameters
Field | Type | Mandatory | Description |
---|---|---|---|
redirectUrl | String | M | URL to redirect to after customer completes verification on ShopeePay.
|
scopes | String | M | The scopes of the authorization.
|
state | String | M | Random string for CSRF protection.
|
merchantId | String | M | Unique identifier of merchant in merchant system.
|
seamlessData | String | O | Require if merchant want ShopeePay to validate whether the phone number matched with user ShopeePay account |
| String | O | Registered phone number of the customer on merchant's platform, to be provided with the country code and without the plus sign.
|
| String | O | Please refer sample below to know how to include seamlessSign. The steps to generate seamlessSign are:
|
Sample API Request
The following script is a sample to generate seamlessData and seamlessSign:
1. Generate seamlessData
EXAMPLE
seamlessData = URLEncode(message)message = {"mobileNumber":"123456789"}seamlessData = %7B%22mobileNumber%22%3A%22123456789%22%7D
Copy
2. Sign seamlessData using algorithm SHA256withRSA and your own private key.
EXAMPLE
rawSign = SHA256withRSA(seamlessData, privateKey)
Copy
3. Generate the seamlessSign by applying base64 encoding and URL encoding
EXAMPLE
seamlessSign = URLEncode(Base64Encode(rawSign))
Copy
Java
JAVA EXAMPLE
package seamless;import java.net.URLEncoder;import java.nio.charset.StandardCharsets;import java.security.KeyFactory;import java.security.Signature;import java.security.spec.PKCS8EncodedKeySpec;import java.util.Base64;public class SeamlessSign {static final String privKey = "-----BEGIN PRIVATE KEY-----\n" +"..." +"-----END PRIVATE KEY-----";public static String getSeamlessSign(String seamlessData) throws Exception{//read private keyString privKeyPEM = privKey.replace("-----BEGIN PRIVATE KEY-----", "").replaceAll("\n", "").replace("-----END PRIVATE KEY-----", "");byte[] decodedKey = Base64.getDecoder().decode(privKeyPEM);KeyFactory keyFactory = KeyFactory.getInstance("RSA");PKCS8EncodedKeySpec keySpec = new PKCS8EncodedKeySpec(decodedKey);//init and prepare Signature instanceSignature signature = Signature.getInstance("SHA256withRSA");signature.initSign(keyFactory.generatePrivate(keySpec));signature.update(seamlessData.getBytes(StandardCharsets.UTF_8));//generate raw signbyte[] rawSign = signature.sign();//base64 encode the raw signString signBase64 = Base64.getEncoder().encodeToString(rawSign);//URL escape the string before placing it as part of the GET parameter in the URL.return URLEncoder.encode(signBase64, "UTF8");}public static String getSeamlessData(String message) throws Exception {return URLEncoder.encode(message, "UTF8");}public static void main(String[] args) throws Exception {String message = "{\"mobileNumber\":\"085179787976\"}";System.out.println(getSeamlessSign(getSeamlessData(message)));}}
Copy
Response Parameter
Field | Type | Mandatory | Description |
---|---|---|---|
state | String | M | Random string for CSRF protection. |
responseMessage | String | M | Debug message to provide more information. |
responseCode | String | M | Error code to specify the error returned. |
authCode | String | M | This authorization code that merchant must append to the provided staticURL when redirecting user to Shopee mobile web or app for account binding |
Sample API Response
RESPONSE
{"responseCode": "2001000","responseMessage": "Successful","authCode": "sample_auth_code","state": "123dskfhknbk2b4kblnasldhfikbfkqw"}
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 | 10 | 00 | 2001000 | Successful | Mark AL(Account Linking) generate process to Success. Forward customer to Shopeepay page |
400 | 10 | 00 | 4001000 | Bad Request | Mark AL generate process to Failed. Retry request with proper parameter |
400 | 10 | 01 | 4001001 |
| Mark AL generate process to Failed. Retry request with proper parameter |
400 | 10 | 02 | 4001002 |
| Mark AL generate process to Failed. Retry request with proper parameter |
401 | 10 | 00 | 4011000 | Unauthorized.{error message} | Mark AL generate process to Failed. Retry request with proper parameter |
401 | 10 | 01 | 4011001 | Invalid Token | Mark AL generate process to Failed. Retry request with proper parameter |
403 | 10 | 01 | 4031001 | Feature Not Allowed. Account Binding Is Not Supported | Mark AL generate process to Failed. Contact Shopeepay to check merchant/store supported product flow |
403 | 10 | 05 | 4031005 | Do Not Honor. User Is Deleted Invalid Field Format {mobileNumber}. User Is Not Found Do Not Honor. User Is Banned Do Not Honor. User Is Locked Do Not Honor. User Is Not Active Do Not Honor | Mark AL generate process to Failed. Retry request periodically or contact Shopeepay to check the user/account status |
403 | 10 | 15 | 4031015 | Transaction Not Permitted. Maximum Active Binding Count Treshold Is Reached | Mark AL generate process to Failed. Retry request periodically or consult to Shopeepay |
404 | 10 | 08 | 4041008 | Invalid Merchant, Status Is Not Active | Mark AL generate process to Failed. Contact Shopeepay to check merchant/store status |
409 | 10 | 00 | 4091000 | Conflict | Mark AL generate process to Failed. Retry request periodically or consult to Shopeepay |
500 | 10 | 00 | 5001000 | General Error | Mark AL generate process to Failed. Retry request periodically or consult to Shopeepay |
500 | 10 | 01 | 5001001 | Internal Server Error | Mark AL generate process to Failed. Retry request periodically or consult to Shopeepay |
504 | 10 | 00 | 5041000 | Timeout | Mark AL generate process to Failed. Retry request periodically or consult to Shopeepay |
Get Account Token
- Use this endpoint to initiate the account linking process of a ShopeePay account to your platform.
- 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 | 07 |
Path | .../v1.0/registration-account-binding |
Version | v1.0 |
Request Parameters
Field | Type | Mandatory | Description |
---|---|---|---|
merchantId | String | M | Unique identifier of merchant in merchant system.
|
authCode | String | C |
|
partnerReferenceNo | String | C | Unique identifier of the account binding request.
|
Sample API Request
Sample API Request using authCode
REQUEST
{"merchantId": "Merchant123","authCode": "ATXGbzzNg5daW"}
Copy
Sample API Request using partnerReferenceNo
REQUEST
{"merchantId": "Merchant123","partnerReferenceNo": "hq05cEwuIva07Jk51vBDykhxdIoU5fp4"}
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. |
referenceNo | String | C | Binding identifier in ShopeePay system. |
accountToken | String | M | The accountToken used to identify the ShopeePay account to be linked.
|
additionalInfo | Object | O | |
| String | O | Unique identifier for a ShopeePay user. |
Sample API Response
RESPONSE
{"responseCode": "2000700","responseMessage": "Successful","referenceNo": "Linking-123","accountToken": "+TgdOx95GGgt3kN7m1ITWDGqCTAVYysV","additionalInfo": {"userIdHash": "15e455125fba426a42bb9145b3af2906813a7f222f6eab93b026ead62dc8d76"}}
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 | 07 | 00 | 2000700 | Successful | Mark AL(Account Linking) binding process to Success. Store response.accountToken |
400 | 07 | 00 | 4000700 | Bad Request | Mark AL binding process to Pending. Retry request with proper parameter |
400 | 07 | 02 | 4000702 |
| Mark AL binding process to Pending. Retry request with proper parameter |
401 | 07 | 00 | 4010700 | Unauthorized.{error message} | Mark AL binding process to Pending. Retry request with proper parameter |
401 | 07 | 01 | 4010701 | Invalid Token | Mark AL binding process to Pending. Retry request with proper parameter |
403 | 07 | 01 | 4030701 | Feature Not Allowed. Account Binding Is Not Supported | Mark AL binding process to Failed. Contact Shopeepay to check merchant/store supported product flow |
403 | 07 | 05 | 4030705 |
| Mark AL binding process to Failed. Retry create a new binding or contact Shopeepay to check the user/account status |
403 | 07 | 15 | 4030715 | Transaction Not Permitted. Maximum Active Binding Count Treshold Is Reached | Mark AL binding process to Failed. |
404 | 07 | 08 | 4040708 | Invalid Merchant, Status Is Not Active | Mark AL binding process to Failed. Contact Shopeepay to check merchant/store status |
404 | 07 | 11 | 4040711 | Account Information Invalid | Mark AL binding process to Pending. Retry request with proper parameter (authCode or partnerReferenceNo) |
409 | 07 | 00 | 4090700 | Conflict | Mark AL binding process to Pending. Retry request periodically or consult to Shopeepay |
500 | 07 | 00 | 5000700 | General Error | Mark AL binding process to Pending. Retry request periodically or consult to Shopeepay |
500 | 07 | 01 | 5000701 | Internal Server Error | Mark AL binding process to Pending. Retry request periodically or consult to Shopeepay |
504 | 07 | 00 | 5040700 | Timeout | Mark AL binding process to Pending. Retry request periodically or consult to Shopeepay |
Request for Account Unlinking
- Use this endpoint to unlink a ShopeePay account from a Customer’s account on your platform.
- 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 | 09 |
Path | .../v1.0/registration-account-unbinding |
Version | v1.0 |
Request Parameter
Field | Type | Mandatory | Description |
---|---|---|---|
merchantId | String | M | Unique identifier of merchant in client system.
|
partnerReferenceNo | String | C | Unique identifier of the account binding request.
|
additionalInfo | Object | ||
| String | C | The accountToken used to represent the account binding between Client’s platform and ShopeePay.
|
Sample API Request
REQUEST
{"merchantId": "Merchant123","partnerReferenceNo": "hq05cEwuIva07Jk51vBDykhxdIoU5fp4","additionalInfo": {"accountToken": "+TgdOx95GGgt3kN7m1ITWDGqCTAVYysV"}}
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 the account binding request. |
merchantId | String | O | Unique identifier of merchant in merchant system. |
additionalInfo | Object | O | |
| String | O | The account token used to identify the ShopeePay account to be linked.
|
| int32 | O | Status of the binding.
|
| String | O | Create time of this individual binding. |
| String | O | Update time of this individual binding. |
| String | O | Unique identifier for a ShopeePay user. |
Sample API Response
RESPONSE
{"responseCode": "2009000","responseMessage": "Successful","partnerReferenceNo": "AccountBinding-123","accountToken": "+TgdOx95GGgt3kN7m1ITWDGqCTAVYysV","merchantId": "Merchant123","additionalInfo": {"bindingStatus": 3,"createTime": "2022-07-20T08:00:00+07:00","updateTime": "2022-07-20T08:00:00+07:00","userIdHash": "15e455125fba426a42bb9145b3af2906813a7f222f6eab93b026ead62dc8d76","accountToken": "+TgdOx95GGgt3kN7m1ITWDGqCTAVYysV"}}
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 | 09 | 00 | 2000900 | Successful | Mark AL(Account Linking) unbinding process to Success |
400 | 09 | 00 | 4000900 | Bad Request | Mark AL unbinding process to Pending. Retry request with proper parameter |
400 | 09 | 01 | 4000901 | Invalid Field Format | Mark AL unbinding process to Pending. Retry request with proper parameter |
400 | 09 | 02 | 4000902 |
| Mark AL unbinding process to Pending. Retry request with proper parameter |
401 | 09 | 00 | 4010900 | Unauthorized.{error message} | Mark AL unbinding process to Pending. Retry request with proper parameter |
401 | 09 | 01 | 4010901 | Invalid Token | Mark AL unbinding process to Pending. Retry request with proper parameter |
403 | 09 | 01 | 4030901 | Feature Not Allowed | Mark AL unbinding process to Pending. Contact Shopeepay to check merchant/store supported product flow |
403 | 09 | 05 | 4030905 |
| Mark AL unbinding process to Pending. Contact Shopeepay to check the user/account status |
403 | 09 | 15 | 4030915 | Transaction Not Permitted. There Is An Ongoing Payment For This Account | Mark AL unbinding process to Pending. Retry request periodically or consult to Shopeepay |
404 | 09 | 11 | 4040911 | Account Information Invalid | Mark AL unbinding process to Pending. Retry request with proper parameter (authCode or partnerReferenceNo) |
404 | 09 | 18 | 4040918 | Inconsistent Request | Mark AL unbinding process to Pending. Retry request with proper parameter |
409 | 09 | 00 | 4090900 | Conflict | Mark AL unbinding process to Pending. Retry request periodically or consult to Shopeepay |
500 | 09 | 00 | 5000900 | General Error | Mark AL unbinding process to Pending. Retry request periodically or consult to Shopeepay |
500 | 09 | 01 | 5000901 | Internal Server Error | Mark AL unbinding process to Pending. Retry request periodically or consult to Shopeepay |
504 | 09 | 00 | 5040900 | Timeout | Mark AL unbinding process to Pending. Retry request periodically or consult to Shopeepay |
Get User Info
- Use this endpoint to get customer’s ShopeePay account information for display purposes.
- 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 | 08 |
Path | .../v1.0/registration-account-inquiry |
Version | v1.0 |
Request Parameter
Field | Type | Mandatory | Description |
---|---|---|---|
partnerReferenceNo | String | C | Unique identifier of the account binding request.
|
additionalInfo | Object | C | |
| String | C | The accountToken used to represent the account binding between Merchant platform and ShopeePay.Either accountToken or partnerReferenceNo should be provided in the request. |
Sample API Request
REQUEST
{"additional_info": {"accountToken": "+TgdOx95GGgt3kN7m1ITWDGqCTAVYysV"}}
Copy
Response Parameter
Field | Sub-Fields | 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 the account binding request. | |
referenceNo | String | C | Transaction identifier in ShopeePay system.
| |
accountNo | String | O | Masked phone number of the customer’s linked ShopeePay account. Example: ********1234 This value is returned if permission is allowed via merchant’s contract with ShopeePay | |
additionalInfo | O | |||
| String | O | Create time of this individual linking.
| |
| String | O | Update time of this individual linking.
| |
| String | O | Unique identifier of merchant in client system. | |
| String | O | Identifier for customer that made the payment. | |
| int32 | O | Status of this binding 1 - Active 2 - Inactive (could be reverted back to Active) 3 - Invalid | |
| String | O | Wallet balance.
| |
| String | O | Coin balance. Only available if customer allow coin redemption for their account. | |
| Boolean | O | Potential values:
| |
| Object | O | SPay Later information. This field will be returned if merchant enable SPayLater as payment method in Link & Pay flow. | |
| String | O | Available Credit
| |
| String | O | Information relates to the SPayLater status. Potential values:
|
Sample API Response
RESPONSE
{"responseCode": "2000800","responseMessage": "Successful","partnerReferenceNo": "OmFbeFkoGd7rXchp9WRzAcTcDy5rgYRq","accountNo": "**6666","additionalInfo": {"createTime": "2024-07-21T13:16:27+07:00","updatetime": "2024-07-21T14:22:26+07:00","merchantId": "openapi5_m8","userIdHash": "8bf7b275f96561518e506954ff427c587cb7ca38cbe07716c551549bc8b526cc","bindingStatus": 1,"walletBalance": "1771375.00","kycPassed": false,"spaylaterInfo": {"availableBalance": "3500000.00","statusInfo": "active"}},"referenceNo": "109886568500762737"}
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 | 08 | 00 | 2000800 | Successful | Mark inquiry account process to Success. Get binding status from response.additionalInfo.bindingStatus |
400 | 08 | 00 | 4000800 | Bad Request | Mark inquiry account process to Failed. Retry request with proper parameter |
400 | 08 | 01 | 4000801 | Invalid Field Format | Mark inquiry account process to Failed. Retry request with proper parameter |
400 | 08 | 02 | 4000802 |
| Mark inquiry account process to Failed. Retry request with proper parameter |
401 | 08 | 00 | 4010800 | Unauthorized.{error message} | Mark inquiry account process to Failed. Retry request with proper parameter |
401 | 08 | 01 | 4010801 | Invalid Token | Mark inquiry account process to Failed. Retry request with proper parameter |
403 | 08 | 05 | 4030805 |
| Mark inquiry account process to Failed. Contact Shopeepay to check the user/account status |
404 | 08 | 11 | 4040811 | Account Information Invalid | Mark inquiry account process to Failed. Retry request with proper parameter |
404 | 08 | 13 | 4040813 | Invalid Amount. Currency Does Not Support Cents | Mark inquiry account process to Failed. Retry request with proper parameter |
409 | 08 | 00 | 4090800 | Conflict | Mark inquiry account process to Failed. Retry request periodically or consult to Shopeepay |
500 | 08 | 00 | 5000800 | General Error | Mark inquiry account process to Failed. Retry request periodically or consult to Shopeepay |
500 | 08 | 01 | 5000801 | Internal Server Error | Mark inquiry account process to Failed. Retry request periodically or consult to Shopeepay |
504 | 08 | 00 | 5040800 | Timeout | Mark inquiry account process to Failed. Retry request periodically or consult to Shopeepay |