Account Linking

ShopeePay offers the following functionalities for account linking and payment use cases:

Merchant Workflow

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

  1. Initiate Get Auth Code when customer chooses to link their ShopeePay account.

  2. Bring the user to SPP's frontend to complete the authorization

  3. Get access token by using returned partnerReferenceNo, and save token for future use cases (e.g. to obtain user information).

  4. Initiate a payment request (via Link & Pay, Subscription, and Authorization & Capture) when customer selects to pay or when payment is due.

  1. 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.
  2. ShopeePay returns an authCode which should be appended to the provided static URL, allowing merchants to direct users to ShopeePay's linking agreement page.
  3. The customer agrees to link their account to the merchant.
  4. Upon successful linking, the customer returns back to the merchant’s page as indicated in the redirectUrl in the Account Linking request, along with an authCode, partnerReferenceNo
  5. Merchant can reply on the authCode or partnerReferenceNo passed by its frontend, to call the /registration-account binding endpoint
  6. Once the merchant obtains the account token, they should save it securely for future use.
  7. 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

Specification

The following table is specification of this API:

HTTP MethodGET
Service Code10
Path.../v1.0/get-auth-code
Versionv1.0

Request Parameters

FieldTypeMandatoryDescription
redirectUrlStringMURL to redirect to after customer completes verification on ShopeePay.
  • For a common URL which starts with ‘http’ or ‘https’, ShopeePay merchants will open it with the default browser.
  • For others (for example, some_app://xxxxx), ShopeePay merchants will try to open the application registered with the schema.
scopesStringMThe scopes of the authorization.
  • Only accepts “ACCOUNT_BINDING” value.
stateStringMRandom string for CSRF protection.
  • Accepts up to 32 characters.
merchantIdStringMUnique identifier of merchant in merchant system.
  • Accepts up to 64 characters.
seamlessDataStringORequire if merchant want ShopeePay to validate whether the phone number matched with user ShopeePay account
  • mobileNumber
StringORegistered phone number of the customer on merchant's platform, to be provided with the country code and without the plus sign.
  • Example:
    • An Indonesian phone number "82112345678" should be passed in as "6282112345678", with 62 being the country code.
  • seamlessSign
StringOPlease refer sample below to know how to include seamlessSign.

The steps to generate seamlessSign are:
  1. The partner uses the private key to sign seamlessData, while ShopeePay will use the partner's public key for the verification process
  2. Sign the seamlessData with generated privateKey and algorithm SHA256withRSA
  3. EncodeBase64 the result of seamlessData which already signed by private key (Second Step)
  4. URLEncode the result of base64 encoded string (Third Step)

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
arrow-svg

Copy

2. Sign seamlessData using algorithm SHA256withRSA and your own private key.

EXAMPLE

rawSign = SHA256withRSA(seamlessData, privateKey)
arrow-svg

Copy

3. Generate the seamlessSign by applying base64 encoding and URL encoding

EXAMPLE

seamlessSign = URLEncode(Base64Encode(rawSign))
arrow-svg

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 key
String 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 instance
Signature signature = Signature.getInstance("SHA256withRSA");
signature.initSign(keyFactory.generatePrivate(keySpec));
signature.update(seamlessData.getBytes(StandardCharsets.UTF_8));
//generate raw sign
byte[] rawSign = signature.sign();
//base64 encode the raw sign
String 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)));
}
}
arrow-svg

Copy

Response Parameter

FieldTypeMandatoryDescription
stateStringMRandom string for CSRF protection.
responseMessageStringMDebug message to provide more information.
responseCodeStringMError code to specify the error returned.
authCodeStringMThis 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"
}
arrow-svg

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 CodeService CodeSub-error CodeResponse CodeResponse MessagePartner Action
20010002001000SuccessfulMark AL(Account Linking) generate process to Success. Forward customer to Shopeepay page
40010004001000Bad RequestMark AL generate process to Failed. Retry request with proper parameter
40010014001001
  • Invalid field format {fieldName}
  • Invalid Field Format
Mark AL generate process to Failed. Retry request with proper parameter
40010024001002
  • Invalid mandatory field {fieldName}
  • Invalid mandatory field {merchantId}. Exceed maximum character length
  • Invalid Mandatory Field {seamlessSign}
  • Invalid Mandatory Field {merchantId}
  • Invalid Mandatory Field + {error message}
Mark AL generate process to Failed. Retry request with proper parameter
40110004011000Unauthorized.{error message}Mark AL generate process to Failed. Retry request with proper parameter
40110014011001Invalid TokenMark AL generate process to Failed. Retry request with proper parameter
40310014031001Feature Not Allowed. Account Binding Is Not SupportedMark AL generate process to Failed. Contact Shopeepay to check merchant/store supported product flow
40310054031005Do 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 HonorMark AL generate process to Failed. Retry request periodically or contact Shopeepay to check the user/account status
40310154031015Transaction Not Permitted. Maximum Active Binding Count Treshold Is ReachedMark AL generate process to Failed. Retry request periodically or consult to Shopeepay
40410084041008Invalid Merchant, Status Is Not ActiveMark AL generate process to Failed. Contact Shopeepay to check merchant/store status
40910004091000ConflictMark AL generate process to Failed. Retry request periodically or consult to Shopeepay
50010005001000General ErrorMark AL generate process to Failed. Retry request periodically or consult to Shopeepay
50010015001001Internal Server ErrorMark AL generate process to Failed. Retry request periodically or consult to Shopeepay
50410005041000TimeoutMark AL generate process to Failed. Retry request periodically or consult to Shopeepay

Get Account Token

Specification

The following table is a specification of this API:

HTTP MethodPOST
Service Code07
Path.../v1.0/registration-account-binding
Versionv1.0

Request Parameters

FieldTypeMandatoryDescription
merchantIdStringMUnique identifier of merchant in merchant system.
  • Accepts up to 64 characters.
authCodeStringC
partnerReferenceNoStringCUnique identifier of the account binding request.
  • The partnerReferenceNo is returned by ShopeePay when the user is redirected to the "redirectUrl" specified by Client in Get Auth API
  • Either authCode or partnerReferenceNo should be provided in the request.
    • Result codes:
      • 100 - User Authentication Success
      • 201 - Account Binding Failed
  • Merchants must store this securely in their systems and pass this in the subsequent payment requests.

Sample API Request

Sample API Request using authCode

REQUEST

{
"merchantId": "Merchant123",
"authCode": "ATXGbzzNg5daW"
}
arrow-svg

Copy

Sample API Request using partnerReferenceNo

REQUEST

{
"merchantId": "Merchant123",
"partnerReferenceNo": "hq05cEwuIva07Jk51vBDykhxdIoU5fp4"
}
arrow-svg

Copy

Response Parameter

FieldTypeMandatoryDescription
responseCodeStringMError code to specify the error returned.
responseMessageStringMDebug message to provide more information.
referenceNoStringCBinding identifier in ShopeePay system.
accountTokenStringMThe accountToken used to identify the ShopeePay account to be linked.
  • Merchants must store this securely in their systems and pass this in the subsequent payment requests.
additionalInfoObjectO
  • userIdHash
StringOUnique identifier for a ShopeePay user.

Sample API Response

RESPONSE

{
"responseCode": "2000700",
"responseMessage": "Successful",
"referenceNo": "Linking-123",
"accountToken": "+TgdOx95GGgt3kN7m1ITWDGqCTAVYysV",
"additionalInfo": {
"userIdHash": "15e455125fba426a42bb9145b3af2906813a7f222f6eab93b026ead62dc8d76"
}
}
arrow-svg

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 codeService CodeSub-Error CodeResponse CodeResponse MessagePartner Action
20007002000700SuccessfulMark AL(Account Linking) binding process to Success. Store response.accountToken
40007004000700Bad RequestMark AL binding process to Pending. Retry request with proper parameter
40007024000702
  • Invalid Mandatory Field {authCode} or {partnerReferenceNo}
  • Invalid mandatory field {merchantId}. Exceed maximum character length
  • Invalid Mandatory Field {merchantId}
  • Invalid Mandatory Field {fieldName}
  • Invalid Mandatory Field + {error message}
Mark AL binding process to Pending. Retry request with proper parameter
40107004010700Unauthorized.{error message}Mark AL binding process to Pending. Retry request with proper parameter
40107014010701Invalid TokenMark AL binding process to Pending. Retry request with proper parameter
40307014030701Feature Not Allowed. Account Binding Is Not SupportedMark AL binding process to Failed. Contact Shopeepay to check merchant/store supported product flow
40307054030705
  • Invalid Field Format {mobileNumber}. User Is Not Found
  • Do Not Honor. User Is Deleted
  • Do Not Honor. User Is Banned
  • Do Not Honor. User Is Locked
  • Do Not Honor. User Is Not Active
  • Do Not Honor
Mark AL binding process to Failed. Retry create a new binding or contact Shopeepay to check the user/account status
40307154030715Transaction Not Permitted. Maximum Active Binding Count Treshold Is ReachedMark AL binding process to Failed.
40407084040708Invalid Merchant, Status Is Not ActiveMark AL binding process to Failed. Contact Shopeepay to check merchant/store status
40407114040711Account Information InvalidMark AL binding process to Pending. Retry request with proper parameter (authCode or partnerReferenceNo)
40907004090700ConflictMark AL binding process to Pending. Retry request periodically or consult to Shopeepay
50007005000700General ErrorMark AL binding process to Pending. Retry request periodically or consult to Shopeepay
50007015000701Internal Server ErrorMark AL binding process to Pending. Retry request periodically or consult to Shopeepay
50407005040700TimeoutMark AL binding process to Pending. Retry request periodically or consult to Shopeepay

Request for Account Unlinking

Specification

The following table is a specification of this API:

HTTP MethodPOST
Service Code09
Path.../v1.0/registration-account-unbinding
Versionv1.0

Request Parameter

FieldTypeMandatoryDescription
merchantIdStringMUnique identifier of merchant in client system.
  • Accepts up to 64 characters.
partnerReferenceNoStringCUnique identifier of the account binding request.
  • Either accountToken or partnerReferenceNo should be provided in the request.
additionalInfoObject
  • accountToken
StringCThe accountToken used to represent the account binding between Client’s platform and ShopeePay.
  • Either accountToken or partnerReferenceNo should be provided in the request.

Sample API Request

REQUEST

{
"merchantId": "Merchant123",
"partnerReferenceNo": "hq05cEwuIva07Jk51vBDykhxdIoU5fp4",
"additionalInfo": {
"accountToken": "+TgdOx95GGgt3kN7m1ITWDGqCTAVYysV"
}
}
arrow-svg

Copy

Response Parameter

FieldTypeMandatoryDescription
responseCodeStringMError code to specify the error returned.
responseMessageStringMDebug message to provide more information.
partnerReferenceNoStringOUnique identifier of the account binding request.
merchantIdStringOUnique identifier of merchant in merchant system.
additionalInfoObjectO
  • accountToken
StringOThe account token used to identify the ShopeePay account to be linked.
  • Merchants must store this securely in their systems and pass this in the subsequent payment requests.
  • bindingStatus
int32OStatus of the binding.
  • 1 - Active
  • createTime
StringOCreate time of this individual binding.
  • updateTime
StringOUpdate time of this individual binding.
  • userIdHash
StringOUnique 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"
}
}
arrow-svg

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 codeService CodeSub-error CodeResponse CodeResponse MessagePartner Action
20009002000900SuccessfulMark AL(Account Linking) unbinding process to Success
40009004000900Bad RequestMark AL unbinding process to Pending. Retry request with proper parameter
40009014000901Invalid Field FormatMark AL unbinding process to Pending. Retry request with proper parameter
40009024000902
  • Invalid Mandatory Field {accountToken or partnerReferenceNo}
  • Invalid Mandatory Field {merchantId}
  • Invalid mandatory field {fieldName}
  • Invalid mandatory field {merchantId}. Exceed maximum character length
  • Invalid Mandatory Field + {error message}
Mark AL unbinding process to Pending. Retry request with proper parameter
40109004010900Unauthorized.{error message}Mark AL unbinding process to Pending. Retry request with proper parameter
40109014010901Invalid TokenMark AL unbinding process to Pending. Retry request with proper parameter
40309014030901Feature Not AllowedMark AL unbinding process to Pending. Contact Shopeepay to check merchant/store supported product flow
40309054030905
  • Invalid Field Format {mobileNumber}. User Is Not Found
  • Do Not Honor. User Is Deleted
Mark AL unbinding process to Pending. Contact Shopeepay to check the user/account status
40309154030915Transaction Not Permitted. There Is An Ongoing Payment For This AccountMark AL unbinding process to Pending. Retry request periodically or consult to Shopeepay
40409114040911Account Information InvalidMark AL unbinding process to Pending. Retry request with proper parameter (authCode or partnerReferenceNo)
40409184040918Inconsistent RequestMark AL unbinding process to Pending. Retry request with proper parameter
40909004090900ConflictMark AL unbinding process to Pending. Retry request periodically or consult to Shopeepay
50009005000900General ErrorMark AL unbinding process to Pending. Retry request periodically or consult to Shopeepay
50009015000901Internal Server ErrorMark AL unbinding process to Pending. Retry request periodically or consult to Shopeepay
50409005040900TimeoutMark AL unbinding process to Pending. Retry request periodically or consult to Shopeepay

Get User Info

Specification

The following table is a specification of this API:

HTTP MethodPOST
Service Code08
Path.../v1.0/registration-account-inquiry
Versionv1.0

Request Parameter

FieldTypeMandatoryDescription
partnerReferenceNoStringCUnique identifier of the account binding request.
  • Either accountToken or partnerReferenceNo should be provided in the request.
additionalInfoObjectC
  • accountToken
StringCThe 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"
}
}
arrow-svg

Copy

Response Parameter

FieldSub-FieldsTypeMandatoryDescription
responseCodeStringMError code to specify the error returned.
responseMessageStringMDebug message to provide more information.
partnerReferenceNoStringOUnique identifier of the account binding request.
referenceNoStringCTransaction identifier in ShopeePay system.
  • This value will be returned upon successful request.
accountNoStringOMasked 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
additionalInfoO
  • createTime
StringOCreate time of this individual linking.
  • Using ISO-8601 timestamp format.
  • updateTime
StringOUpdate time of this individual linking.
  • Using ISO-8601 timestamp format.
  • merchantId
StringOUnique identifier of merchant in client system.
  • userIdHash
StringOIdentifier for customer that made the payment.
  • bindingStatus
int32OStatus of this binding 1 - Active 2 - Inactive (could be reverted back to Active) 3 - Invalid
  • walletBalance
StringOWallet balance.
  • This value is returned if permission is allowed via merchant’s contract with ShopeePay.
  • coinBalance
StringOCoin balance. Only available if customer allow coin redemption for their account.
  • kycPassed
BooleanOPotential values:
  • True - User passed full KYC
  • False - User has not passed KYC yet This value is returned if permission is allowed via merchant’s contract with ShopeePay.
  • spaylaterInfo
ObjectOSPay Later information. This field will be returned if merchant enable SPayLater as payment method in Link & Pay flow.
  • availableBalance
StringOAvailable Credit
  • This value is returned if permission is allowed via merchant’s contract with ShopeePay and if the customer has an active SPayLater account.
  • statusInfo
StringOInformation relates to the SPayLater status. Potential values:
  • active
  • inactive
  • unavailable

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"
}
arrow-svg

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 codeService CodeSub-error CodeResponse CodeResponse MessagePartner Action
20008002000800SuccessfulMark inquiry account process to Success. Get binding status from response.additionalInfo.bindingStatus
40008004000800Bad RequestMark inquiry account process to Failed. Retry request with proper parameter
40008014000801Invalid Field FormatMark inquiry account process to Failed. Retry request with proper parameter
40008024000802
  • Invalid Mandatory Field {accountToken or partnerReferenceNo}
  • Invalid Mandatory Field {merchantId}
  • Invalid Mandatory Field + {error message}
Mark inquiry account process to Failed. Retry request with proper parameter
40108004010800Unauthorized.{error message}Mark inquiry account process to Failed. Retry request with proper parameter
40108014010801Invalid TokenMark inquiry account process to Failed. Retry request with proper parameter
40308054030805
  • Do Not Honor. User Is Deleted
  • Do Not Honor. User Is Banned
  • Do Not Honor. User Is Locked
  • Do Not Honor. User Is Not Active
  • Invalid Field Format {mobileNumber}. User Is Not Found
Mark inquiry account process to Failed. Contact Shopeepay to check the user/account status
40408114040811Account Information InvalidMark inquiry account process to Failed. Retry request with proper parameter
40408134040813Invalid Amount. Currency Does Not Support CentsMark inquiry account process to Failed. Retry request with proper parameter
40908004090800ConflictMark inquiry account process to Failed. Retry request periodically or consult to Shopeepay
50008005000800General ErrorMark inquiry account process to Failed. Retry request periodically or consult to Shopeepay
50008015000801Internal Server ErrorMark inquiry account process to Failed. Retry request periodically or consult to Shopeepay
50408005040800TimeoutMark inquiry account process to Failed. Retry request periodically or consult to Shopeepay