Link & Pay

Merchant Workflow

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

Completed account linking request and store returned account token
Optional: to retrieve user information or coin redemption using account token
Initiate a payment request for Link & Pay when customer selects to pay

The following figure illustrates the workflow of accepting a payment in the Link & Pay payment scenario:

Optionally, before initiating a payment, the merchant can call the two endpoints below based on the use cases
- Get User Information: ShopeePay will inform the merchant of the customer’s current wallet balance, KYC status etc, should the merchant require any such checks beforehand.
Merchant calls Create Payment Order: Link & Pay endpoint to create payment for the customer. ShopeePay will return a redirect_url for the merchant to allow the user to enter.
Customer selects a payment method and confirms payment.
ShopeePay processes the payment and returns the customer back to the merchant’s page.
ShopeePay will sends an asynchronous message via Notify Payment Status endpoint to inform merchants on the payment result.
Merchants must call the Check Transaction Status endpoint to query the status of the transaction.
- If the response code is "Success" and the latestTransactionStatus is 00, 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 30 minutes.
- 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 30 minutes.
For Refund, if the transaction is in a Processing status or has no response, keep inquiring with an incremental frequency up to 24 hours.

NOTE: When integrating with our LnP product flow, please do not perform any balance validation on the user’s account. Once the user is redirected to ShopeePay, they will have the flexibility to choose from multiple payment methods available other than ShopeePay wallet balance.

Create Payment Order: Link & Pay

Use this endpoint to create a payment with an access token and a hosted-checkout page
All API requests require a header. Refer to API Param Specification → Transaction Request

Specification

The following table is the specification of the API:

HTTP Method	POST
Service Code	54
Path	.../v1.0.2/debit/payment-host-to-host
Version	v1.0.2

Request Parameter

Field	Type	Mandatory	Description
partnerReferenceNo	String	M	Unique identifier of payment transaction generated by merchant.
merchantId	String	M	Unique identifier of merchant in merchant system. Accepts up to 64 characters.
externalStoreId	String	M	Unique identifier of store in merchant system. Accepts up to 64 characters.
amount	Object	M
value	String	M	Transaction amount. Sample: 10.000,00 will be placed with 10000.00
currency	String	M	Currency that is associated with the payment amount. Accepted values: IDR
validUpTo	String	O	Accepts up to 1,800 seconds (30 mins), from the time request was received If this field is filled, `partnerReferenceNo` in this request will expire after the specified time period (in seconds) and payment attempt to this `partnerReferenceNo` will fail. Using ISO 8601 timestamp format.
urlParams	Array of Object	M	Array of object
url	String	M	Indicates the URL of the merchant's platform to return back to, once the payment on ShopeePay’s page is completed.
type	String	M	Indicates the type of the sent url. Only accepts ‘PAY_RETURN' value.
isDeepLink	String	M	Indicates whether the url is a deep link or not. Only accepts either ‘Y’ or ‘N’ value.
additionalInfo	Object	O
accountToken	String	M	The `accountToken` used to represent the account binding between Merchant's platform and ShopeePay.
useCoin	Boolean	O	Use this field to indicate whether the customer prefers to use or not to use coins to offset their payment on the merchant’s platform. The default value is set to false. True: attempt to use coins False: do not use coins
promoIds	String	O	Comma separated eligible promoIds of 100 characters or less (up to 20), if any. These promoIds will be checked against promotional campaigns configured in ShopeePay to determine the valid reward amount the customer can receive for this transaction.
metadata	String	O	Additional information for the transaction. Additional information for the transaction. This field supports up to 3 fields and needs to be sent in this format {\”field1\”:\”{Data1}\”,\”field2\”:\”{Data2}\” ,\”field3\”:\”{Data3}\”}

Sample API Request

REQUEST

"partnerReferenceNo": "Direct Payment-123",
  "merchantId": "Merchant123",
  "externalStoreId": "Store123",
  "amount": {
    "value": "10000.00",
    "currency": "IDR"
  },
  "validUpTo": "2022-07-20T07:00:00+07:00",
  "urlParams": [
    {
      "url": "https://www.test.com",
      "type": "PAY_RETURN",
      "isDeepLink": "N"
    }
  ],
  "additionalInfo": {
    "useCoin": true,
    "accountToken": "+Tgd0x95GGgt3kN7m1ItWDGqCTAVYysV",
    "promoIds": "Promo1, Promo2",
    "metadata": "{\"field1\":\"Data1\",\"field2\":\"Data2\",\"field3\":\"Data3\"}"
  }
}

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.
webRedirectUrl	String	O	The URL for the merchant's front-end to redirect the user to ShopeePay's page. Merchant should not impose any kind of restrictions for this URL, such as: Whitelisting only specific domains Restricting specific IPs Limiting URL length The maximum length for the webRedirectUrl parameter is 2048 chars

Sample API Response

JS EXAMPLE

{
  "responseCode": "2005400",
  "responseMessage": "Successful",
  "webRedirectUrl": "https://uat.shopee.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 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	54	00	2005400	Successful	Mark LnP (Link&Pay) generate process to Success. Forward customer to Shopeepay page
400	54	00	4005400	Bad Request	Mark LnP (Link&Pay) generate process to Failed. Retry request with proper parameter
400	54	01	4005401	Invalid field format {fieldName} Invalid field format {timestamp} Invalid Field Format {validUpTo} Invalid Field Format {promoIds} Invalid Field Format {paymentChannelId} Invalid Field Format {paymentChannelName} Invalid Field Format {paymentMethodName} Invalid Field Format {fraudCheckInfo} Invalid field format {currency} Invalid Field Format {metadata}. Exceed Maximum Characters Invalid Field Format {metadata}. Maximum JSON Key Exceeded Invalid Field Format {metadata}. Invalid JSON Key Name Invalid Field Format {metadata} Invalid Field Format	Mark LnP (Link&Pay) generate process to Failed. Retry request with proper parameter
400	54	02	4005402	Invalid mandatory field {fieldName} Invalid mandatory field {originalPartnerReferenceNo} Invalid mandatory field {merchantId}. Exceed maximum character length Invalid mandatory field {externalStoreId}. Exceed maximum character length Invalid Mandatory Field {currency} Invalid Mandatory Field {merchantId} Invalid Mandatory Field {pointOfInitiation} Invalid Mandatory Field {externalStoreId} Invalid Mandatory Field {pointOfInitiation} or {accountToken} Invalid Mandatory Field {value}. Non Positive Amount Is Not Allowed Invalid Mandatory Field + {error message}	Mark LnP (Link&Pay) generate process to Failed. Retry request with proper parameter
401	54	00	4015400	Unauthorized. Invalid Client Key Unauthorized.{error message}	Mark LnP (Link&Pay) generate process to Failed. Retry request with proper parameter
401	54	01	4015401	Invalid Token	Mark LnP (Link&Pay) generate process to Failed. Retry request with proper parameter
403	54	01	4035401	Feature Not Allowed Feature Not Allowed. Selected Payment Channel Is Disabled For Merchant	Mark LnP (Link&Pay) generate process to Failed. Retry request periodically or consult to Shopeepay
403	54	06	4035406	Feature Not Allowed. Service Is Temporarily Down For Scheduled Maintenance	Mark LnP (Link&Pay) generate process to Failed. Retry request periodically or consult to Shopeepay
404	54	08	4045408	Invalid merchant, status is not active Invalid Field Format	Mark LnP (Link&Pay) generate process to Failed. Retry request with proper parameter or Contact Shopeepay to check merchant/store status
404	54	13	4045413	Invalid Amount. Currency Does Not Support Cents	Mark LnP (Link&Pay) generate process to Failed. Retry request with proper parameter
404	54	18	4045418	Inconsistent Request	Mark LnP (Link&Pay) generate process to Failed. Retry request with proper parameter
409	54	00	4095400	Conflict	Mark LnP (Link&Pay) generate process to Failed. Retry request periodically or consult to Shopeepay
500	54	00	5005400	General Error	Mark LnP (Link&Pay) generate process to Failed. Retry request periodically or consult to Shopeepay
500	54	01	5005401	Internal Server Error	Mark LnP (Link&Pay) generate process to Failed. Retry request periodically or consult to Shopeepay
504	54	00	5045400	Timeout	Mark LnP (Link&Pay) generate process to Failed. Retry request periodically or consult to Shopeepay

Check Transaction Status for Link&Pay

Use this endpoint to query the status of a Link&Pay transaction
All API requests require a header. Refer to API Param Specification → Transaction Request

Note:

While a 200xx00 response generally indicates a successful API call, the actual transaction might still be processing in the background. To confirm the latest status of your transaction, we strongly recommend referring to the latestTransctionStatus field in the API response. This will provide the most up-to-date information.

Specification

The following table is the specification of the API:

HTTP Method	POST
Service Code	55
Path	.../v1.0/debit/status
Version	v1.0

Request Parameter

Field	Type	Mandatory	Description
originalPartnerReferenceNo	String	M	Unique identifier of the transaction merchant would like to query, which could be partnerReferenceNo or partnerRefundNo.
merchantId	String	M	Unique identifier of merchant in merchant system.
externalStoreId	String	M	Unique identifier of store in merchant system.
serviceCode	String	M	Service code of original transaction, which could be 54 (Link and Pay transaction) or 58 (refund).
amount	Object	M
value	String	M	Transaction amount Sample: 10.000,00 will be placed with 10000.00
currency	String	M	Currency that is associated with the refund amount Accepted values: IDR

Sample API Request

RESPONSE

{
   "originalPartnerReferenceNo": "Testing-123",
   "merchantId": "Merchant123",
   "externalStoreId": "Store123",
   "serviceCode": "54",
   "amount": {
      "value": "10000.00",
      "currency": "IDR"
   }
}

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
originalReferenceNo	String	C	Transaction identifier in ShopeePay system that is shown to the customer. The value will be returned for successful payment.
originalPartnerReferenceNo	String	O	Unique identifier of the transaction merchant would like to query, which could be partnerReferenceNo or partnerRefundNo.
serviceCode	String	M	Service code of original transaction, which could be 54 (Link and Pay transaction) or 58 (refund).
latestTransactionStatus	String	M	Refer to Transaction Status for specific transaction statuses
transAmount	Object	O
value	String	M	Transaction amount. Sample: 10.000,00 will be placed with 10000.00
currency	String	M	Refers to the currency abbreviation for the transaction. IDR
paidTime	String	C	Update time of the individual transaction. Using ISO-8601 timestamp format.
additionalInfo	Object	O
createTime	String	O	Create time of the individual transaction. Using ISO-8601 timestamp format.
productType	uint32	O	Indicates the payment method used. Refer to Product Types for the respective payment methods
transactionType	uint32	O	Refer to Transaction Types for specific transaction types
merchantId	String	O	Unique identifier of merchant in merchant system.
externalStoreId	String	O	Unique identifier of store in merchant system.
userIdHash	String	O	Unique identifier of the user making the payment.
promoIdApplied	String	O	Comma separated eligible promoIds of 100 characters or less (up to 20), if any. These promoIds will be checked against promotional campaigns configured in ShopeePay to determine the valid reward amount the customer can receive for this transaction.
paymentChannel	int32	O	Indicates the source of fund used. Refer to Payment Channels for the respective source of fund.

Sample API Response

RESPONSE

{
   "responseCode": "2005500",
   "responseMessage": "Successful",
   "original ReferenceNo": "Testing-123",
   "originalPartnerReferenceNo": "Payment-123",
   "serviceCode": "54",
   "latestTransactionStatus": "00",
   "paidTime": "2022-07-20T07:10:10+07:00",
   "transAmount": {
      "value": "10000.00",
      "currency": "IDR"
   },
   "additionalInfo": {
      "createTime": "2022-07-20T07:05:00+07:00",
      "productType": 16,
      "transactionType": 13,
      "userIdHash": "15e455125fba426a4a2bb9145b3af2906813a7f222f6eab93b026ead62dc8d76",
      "merchantId": "Merchant123",
      "externalStoreId": "Store123",
      "promoIdApplied": "Promo1, Promo2",
      "paymentChannel": 1
   }
}

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	55	00	2005500	Successful	Mark LnP (Link&Pay) payment to corresponding status according to response.additionalInfo.latestTransactionStatus. Retry request periodically if didn't get final status
400	55	00	4005500	Bad Request	Mark LnP (Link&Pay) payment to Pending. Retry request with proper parameter
400	55	01	4005501	Invalid field format {fieldName} Invalid field format {serviceCode} Invalid Field Format {metadata}. Exceed Maximum Characters Invalid Field Format {metadata}. Maximum JSON Key Exceeded Invalid Field Format {metadata}. Invalid JSON Key Name Invalid Field Format {metadata} Invalid mandatory field {value}, Non-Positive Amount	Mark LnP (Link&Pay) payment to Pending. Retry request with proper parameter
400	55	01	4005501	Invalid Field Format	Mark LnP (Link&Pay) payment to Pending. Retry request with proper parameter
400	55	02	4005502	Invalid mandatory field {fieldName} Invalid mandatory field {partnerReferenceNo} Invalid mandatory field {merchantId}. Exceed maximum character length Invalid mandatory field {externalStoreId}. Exceed maximum character length Invalid mandatory field {merchantId/externalStoreId} Invalid Amount. Amount cannot contain cents Invalid Mandatory Field + {error message}	Mark LnP (Link&Pay) payment to Pending. Retry request with proper parameter
400	55	08	4005508	Invalid Field format Invalid Merchant	Mark LnP (Link&Pay) payment to Pending. Retry request periodically or consult to Shopeepay
401	55	00	4015500	Unauthorized invalid client key Unauthorized.{error message}	Mark LnP (Link&Pay) payment to Pending. Retry request with proper parameter
401	55	01	4015501	Invalid Token	Mark LnP (Link&Pay) payment to Pending. Retry request with proper parameter
403	55	08	4035508	Invalid Merchant, Status Is Not Active Invalid Store, Status Is Not Active	Mark LnP (Link&Pay) payment to Pending. Contact Shopeepay to check merchant/store status
404	55	01	4045501	Transaction not found	Mark LnP (Link&Pay) payment to Failed
404	55	08	4045508	Entity not found	Mark LnP (Link&Pay) payment to Pending. Retry request periodically or consult to Shopeepay
404	55	13	4045513	Invalid amount. Mismatch with original transaction Invalid Amount. Non Positive Amount Is Not Allowed	Mark LnP (Link&Pay) payment to Pending. Retry request with proper parameter
409	55	00	4095500	Conflict	Mark LnP (Link&Pay) payment to Pending. Retry request periodically or consult to Shopeepay
500	55	00	5005500	General Error	Mark LnP (Link&Pay) payment to Pending. Retry request periodically or consult to Shopeepay
500	55	01	5005501	Internal Server Error	Mark LnP (Link&Pay) payment to Pending. Retry request periodically or consult to Shopeepay
504	55	00	5045500	Timeout	Mark LnP (Link&Pay) payment to Pending. Retry request periodically or consult to Shopeepay

Refund Payment

Use this endpoint to request a refund for a successful transaction. Refunds are subject to refund conditions.

HTTP Method	POST
Service Code	58
Path	../v1.0/debit/refund
Version	v1.0

Refer to Refund Payment for the detail request and response parameters.

Notify Transaction Status

Note: Merchant needs to confirm that both the payment amount and the originalPartnerReferenceNo correspond to the original /debit/payment-host-to-host request before considering the payment successful.

HTTP Method	POST
Service Code	56
Path	.../v1.0/debit/notify
Version	v1.0

Refer to Notify Transaction Status endpoint for the detail request body and response parameters.

Link & Pay

Merchant Workflow

Create Payment Order: Link & Pay

Specification

Request Parameter

Sample API Request

REQUEST

Response Parameter

Sample API Response

JS EXAMPLE

Response Codes

Check Transaction Status for Link&Pay

Specification

Request Parameter

Sample API Request

RESPONSE

Response Parameter

Sample API Response

RESPONSE

Response Codes

Refund Payment

Notify Transaction Status

On this page