ShopeePay Integrationarrow-svg
Get Started with ShopeePay
API Documentationsarrow-svg
Customer Presented ModeMerchant Presented ModeCheckout with ShopeePayAccount LinkingLink & PaySubscriptionAuth & CaptureInvalidate QRInvalidate OrderRefund a PaymentNotify Transaction StatusCheck Transaction Status
Common ObjectsRevision History

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 a account linking request when customer chooses to link their ShopeePay account.

  2. Handle the redirect URL returned.

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

  4. Initiate a payment request (via Link & Pay or Subscription ) 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 Initiate an Account Link endpoint to start the linking process.
  2. ShopeePay returns a redirect_url and this URL can be used by merchant to direct user 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 redirect_url in the Account Link request, along with an auth code. ShopeePay also sends an asynchronous message via Notify Account Link Status endpoint to inform merchants of the successful linking.
  5. Merchant may either rely on the notification callback from ShopeePay, or the auth code passed by its frontend, to call the Get Access Token endpoint.
  6. Once the merchant obtains the access token, they should save it securely for future use.
  7. Should the customer chooses 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 query or charge the customer’s ShopeePay account. ShopeePay also sends an asynchronous message via Notify Account Link Status endpoint to inform merchants of the successful unblinking.

API Documentation

Initiate an Account Linking

Use this endpoint to kick start the account linking process of a ShopeePay account to your platform.

  • URL: "/v3/merchant-host/account/link"

Request Parameters

FieldTypeMandatoryDescription
request_idstringYUnique identifier for each account linking request, accepts up to 64 characters.
return_urlstringYURL to redirect to after customer completes verification on ShopeePay.
linking_reference_idstringNUnique identifier in merchant’s system to identify this linking.
merchant_ext_idstringYUnique identifier of merchant in merchant’s system.
service_namestringNName in merchant’s system to identify this linking service.
service_idstringNdentifier in merchant’s system to identify this service associated with this specific linking.
linking_descriptionstringNGeneral description about this linking.
phonestringYRegistered phone number of the customer on merchant’s platform, to be provided with the country code and without the plus sign.
platform_typestringNType of the merchant’s platform where the customer triggered the account linking flow from.

Sample API Request

REQUEST

{
            "request_id": "input-unique-request-id-here",
            "return_url":"https://isv-domain.com",
            "linking_reference_id": "ref-id-tracking",
            "merchant_ext_id": "external-merchant",
            "service_name": "merchant-name",
            "service_id": "input-service-id-here",
            "linking_description": "input-linking-description-here",
            "phone": "6282112345678",
            "platform_type": "app"
}
arrow-svg

Copy

Response Parameters

FieldTypeDescription
request_idstringThe same value as the 'request_id' in the request.
errcodestringError code to specify the error returned.
debug_msgstringDebug message to provide more information.
redirect_url_webstringIndicates the URL to ShopeePay’s linking agreement page. Merchant should not impose any domain whitelisting and IP restriction for this URL.

Sample API Response

REQUEST

{
            "request_id": "input-unique-request-id-here",
            "errcode": 0,
            "debug_msg": "success",
            "redirect_url_web": "https://app.uat.shopeepay.vn/universal-link/payment/account-linking/pre-link?ticket=131503566697895231",
}
arrow-svg

Copy

Response Code

Please refer to the following description for a general explanation of the errcode returned during an API Response.

For a more detailed explanation, it is advisable to consult debug_msg field. This field provides additional information that can offer valuable insights for troubleshooting.

Merchants may choose to display the debug_msg to their operators or staffs to facilitate prompt identification and resolution of the issue.

ValueDescription
-2A server dropped the connection
-1A server error occurred, merchant may initiate a new account linking request or request using same 'linking_reference_id'
0Success
1The request parameters is invalid or a mandatory parameter is empty
2Permission denied, often due to invalid status
11Duplicated request
305Invalid merchant
300026Invalid or expired QR

Get Access Token

Use this API to get a ShopeePay access token using the linking_reference_id.

  • URL: "/v3/merchant-host/access-token/get"

Request Parameters

FieldTypeMandatoryDescription
request_idstringYUnique identifier for each account linking request, accepts up to 64 characters.
linking_reference_idstringYUnique identifier in merchant’s system to identify this linking, same as what is used in the Create Account Linking endpoint.

Sample API Request with 'linking_reference_id'

REQUEST

{
            "request_id": "input-unique-request-id-here",
            "linking_reference_id": "ref-id-tracking"
}
arrow-svg

Copy

Response Parameters

FieldTypeDescription
request_idstringThe same value as the request_id in the request.
errcodeint32Error code to specify the error returned.
debug_msgstringDebug message to provide more information.
access_tokenstringThe access 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.
user_id_hashstringUnique identifier for a ShopeePay user.
linking_reference_idstringUnique identifier in merchant’s system to identify this linking.
merchant_ext_idstringUnique identifier of merchant in merchant's system.
linking_statusint32Status of this linking, 1 - Active
create_timestringCreate time for this individual linking.
update_timestringUpdate time for this individual linking.

Sample API Response

RESPONSE

{
            "request_id": "input-unique-request-id-here",
            "errcode": 0,
            "debug_msg": "success",
            "access_token": "2r4a56n7o3e56s473t8c2y78e",
            "user_id_hash": "697863f9295aeddcb3db598ecbc74c59a13335abf4d8c41b40e33b28a9d7d63c",
            "merchant_ext_id": "external-merchant",
            "linking_reference_id": "ref-id-tracking",
            "linking_status": 1,
            "create_time": 1708937423,
            "update_time": 1708937423
}
arrow-svg

Copy

Response Code

Please refer to the following description for a general explanation of the errcode returned during an API Response.

For a more detailed explanation, it is advisable to consult debug_msg field. This field provides additional information that can offer valuable insights for troubleshooting.

Merchants may choose to display the debug_msg to their operators or staffs to facilitate prompt identification and resolution of the issue.

ValueDescription
-2A server dropped the connection
-1A server error occurred
0Success
1The request parameters is invalid or a mandatory parameter is empty
2Permission denied, often due to invalid status
9Customer’s account is banned
14Customer’s account is deleted
24Customer’s account is frozen
27Customer’s account is not activated
105Invalid auth code
150Active linking count threshold reached
305Invalid merchant
907Unable to verify customer
300059Bank account not linked

Request for Account Unlinking

Use this endpoint to unlink a ShopeePay account from a customer’s account on your platform.

  • URL: "/v3/merchant-host/account/unlink"

Request Parameters

FieldTypeMandatoryDescription
request_idstringYUnique identifier for each account linking request, accepts up to 64 characters.
linking_reference_idstringYUnique identifier in merchant’s system to identify this linking, same as what is used in the Account Linking endpoint.

Sample API Request

REQUEST

{
            "request_id": "input-unique-request-id-here",
            "linking_reference_id": "ref-id-tracking"
}
arrow-svg

Copy

Response Parameters

FieldTypeDescription
request_idstringThe same value as the request_id in the request.
errcodeint32Error code to specify the error returned.
debug_msgstringDebug message to provide more information.
merchant_ext_idstringUnique identifier of merchant in merchant's system.
linking_statusint32Status of this linking, 3 - Invalid.
create_timestringCreate time for this individual unlinking.
update_timestringUpdate time for this individual unlinking.
access_tokenstringThe access token used to identify a ShopeePay customer’s account.
user_id_hashstringIdentifier for customer that made the payment.
linking_reference_idstringUnique identifier in merchant’s system to identify this linking.

Sample API Response

RESPONSE

{
            "request_id": "input-unique-request-id-here",
            "errcode": 0,
            "debug_msg": "success",
            "access_token": "2r4a56n7o3e56s473t8c2y78e",
            "user_id_hash": "697863f9295aeddcb3db598ecbc74c59a13335abf4d8c41b40e33b28a9d7d63c",
            "merchant_ext_id": "external-merchant",
            "linking_reference_id": "ref-id-tracking",
            "linking_status":3,
            "create_time": 1708937423,
            "update_time": 1708937423
}
arrow-svg

Copy

Response Code

Please refer to the following description for a general explanation of the errcode returned during an API Response.

For a more detailed explanation, it is advisable to consult debug_msg field. This field provides additional information that can offer valuable insights for troubleshooting.

Merchants may choose to display the debug_msg to their operators or staffs to facilitate prompt identification and resolution of the issue.

ValueDescription
-2A server dropped the connection
-1A server error occurred, merchant may initiate a new account unlinking request or request using same 'linking_reference_id'
0Success
1The request parameters is invalid or a mandatory parameter is empty
152Fail to unlink due to ongoing auth
305Invalid merchant
2000A server error occurred

This request will send details of the specific linking lifecycle to the merchant server’s callback URL, which is configured in ShopeePay’s system at the time of onboarding.

Each callback request will contain a signature in the request header. This signature is generated using the ShopeePay-issued secret key, assigned to the merchant receiving the callback request. Merchant should use this signature to verify the authenticity of the callback content.

Multiple repeated notifications might be sent to the merchant and merchant shall be able to handle the repeated notifications with the same contents properly.

Merchants should not impose any check or limit on the sequence nor the length of each field of the callback request.

Note: It is recommended for the merchant using this Callback to validate that the linking_reference_id matches the original account or link request’s linking_reference_id before considering the customer’s action to be completed.

FieldTypeDescription
request_idstringThe same value as the request_id in the request.
linking_reference_idstring

Unique identifier in merchant’s system to identify this linking, same as what is used in the Account Link.

If merchant did not use linking_reference_id in the Account Link, this parameter will be auto-generated by ShopeePay system

merchant_ext_idstringUnique identifier of merchant in client system.
update_typeint64

Status update of this customer's linking status:

  • 1: User successfully authorized the linking
  • 2: User account is linked successfully
  • 3: User token status is invalidated by ShopeePay
  • 4: User has successfully unlinked with the merchant
  • 5: Merchant has successfully unlinked with the user

Sample Callback for Successful User Authorization on ShopeePay

CALLBACK

{
            "request_id": "input-unique-request-id-here",
            "linking_reference_id": "ref-id-tracking",
            "merchant_ext_id": "external-merchant",
            "update_type": 1
}
arrow-svg

Copy

Sample Callback for Unlinking

JS EXAMPLE

{
            "request_id": "input-unique-request-id-here",
            "linking_reference_id": "ref-id-tracking",
            "merchant_ext_id": "external-merchant",
            "update_type": 4
}
arrow-svg

Copy

Use Cases for Get Access Token

Get User Info

Use this endpoint to get customer’s ShopeePay account information for display purposes.

  • URL: "/v3/merchant-host/user-info/get"

Request Parameters

FieldTypeMandatoryDescription
request_idstringYUnique identifier for each account linking request, accepts up to 64 characters.
access_tokenstringYThe access token used to identify the user account.

Sample API Request

REQUEST

{
            "request_id": "input-unique-request-id-here",
            "access_token": "54673258746782637482",
}
arrow-svg

Copy

Response Parameters

FieldTypeDescription
request_idstringThe same value as the request_id in the request.
errcodeint32Error code to specify the error returned.
debug_msgstringDebug message to provide more information.
linking_infoobjectLinking information. Will only be returned if there is any linking found with the linking_reference_id or acess_token provided.
  • linking_reference_id
stringUnique identifier in merchant’s system to identify this linking.
  • linking_status
int32Status of this linking
  • create_time
stringCreate time for this individual linking.
  • update_time
stringUpdate time for this individual linking.
  • merchant_ext_id
stringUnique identifier of merchant in merchant's system.
  • user_id_hash
stringIdentifier for customer that made the payment.
user_infoobjectWill return empty if the ShopeePay account is deleted, banned or frozen.
  • phone_number
stringMasked phone number of the customer’s linked ShopeePay account.
  • wallet_balance
int64Value inflated by 100.
  • spaylater_info
objectSPayLater information. This object, containing the available_balance and the status_info fields, will be returned if merchant enables SPayLater as a payment method.
  • available_balance
int64Value inflated by 100.
  • status_info
int64Information relates to the SPayLater status.
  • coin_balance
int64Value inflated by 100.
  • kyc_passed
booleanTrue: User passed KYC; False: User has not passed KYC.

Sample API Response

RESPONSE

{
            "request_id": "input-unique-request-id-here",
            "errcode": 0,
            "debug_msg": "success",
            "user_info": {
                    "wallet_balance": 0,
                    "spaylater_info": {
                        "available_balance": 45000000,
                        "status_info": "active"
                    },
                    "kyc_passed": true
            },
            "linking_info": {
                    "linking_status": 1,
                    "create_time": 1708937423,
                    "update_time": 1708937423,
                    "user_id_hash": "697863f9295aeddcb3db598ecbc74c59a13335abf4d8c41b40e33b28a9d7d63c",
                    "linking_reference_id": "ref-id-tracking",
                    "merchant_ext_id": "external-merchant"
            }
}
arrow-svg

Copy

Response Code

ValueDescription
-2A server dropped the connection
-1A server error occurred
0Success
1The request parameters is invalid or a mandatory parameter is empty
2Permission denied, often due to invalid status
24Customer's account is frozen
27Customer's account is not activated
305Invalid merchant

Get Coin Redemption Info

Use this endpoint to get the customer's maximum redeemable coin amount in percentage or in absolute amount.

  • URL: "/v3/merchant-host/coin/potential-redemption"

Note: This API is temporarily unavailable for use in Thailand and Vietnam.

Request Parameters

FieldTypeMandatoryDescription
request_idstringYUnique identifier for each account linking request, accepts up to 64 characters.
access_tokenstringYThe access token used to identify the customer's account.
payment_amountint64NPayment amount value inflated by 100. Pass this field if the merchant wants to display the exact amount of redeemable coins for a specific payment.

Sample API Request

REQUEST

{
            "request_id": "input-unique-request-id-here",
            "access_token": "54673258746782637482",
            "payment_amount": 10000
}
arrow-svg

Copy

Response Parameters

FieldTypeDescription
request_idstringThe same value as the request_id in the request.
errcodeint32Error code to specify the error returned.
debug_msgstringDebug message to provide more information.
max_coin_percentageint64Maximum percentage of the payment that can be redeemed by coins.
potential_payment_amountint64Estimated payment amount to be paid after coin redemption, value inflated by 100.
potential_coin_amountint64Maximum amount of coins that can be used in the payment, value inflated by 100.

Sample API Response

REQUEST

{
            "request_id": "input-unique-request-id-here",
            "errcode": 0,
            "debug_msg": "success",
            "max_coin_percentage": 10,
            "potential_payment_amount": 10000,
            "potential_coin_amount": 30
}
arrow-svg

Copy

Response Code

ValueDescription
-2A server dropped the connection
-1A server error occurred
0Success
1The request parameters is invalid or a mandatory parameter is empty
2Permission denied, often due to invalid status
27Customer's account is not activated
305Invalid merchant
702Coin redemption disabled
705Coin redemption disabled

On this page