ShopeePay Logo

Link & Pay

Merchant Workflow

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

  1. Completed account linking request and store returned account token
  2. Optional: to retrieve user information or coin redemption using account token
  3. 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:

  1. 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.
  2. 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.
  3. Customer selects a payment method and confirms payment.
  4. ShopeePay processes the payment and returns the customer back to the merchant's page.
  5. ShopeePay will sends an asynchronous message via Notify Payment Status endpoint to inform merchants on the payment result.
  6. 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.
  7. 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.

Get Payment Methods

Mandatory when the merchant maintains their own end-to-end checkout flow (API-Based flow).

Use this endpoint to retrieve the user's linked payment methods for the transaction. The merchant should display each payment method returned by the API, along with its associated information, on the merchant's frontend for the user to select.

HTTP MethodPOST
Service Code11
Path.../v2.0/balance-inquiry
Versionv2.0

Request Parameters

•additionalInfoObjectConditional

Response Parameters

•responseCodestring

Error code to specify the error returned.

•responseMessagestring

Debug message to provide more information from response code.

•additionalInfoObject

Additional fields in "paymentPromoInfo" depending on promoType

promoTypeAdditional Field(s)TypeDescriptionExample
DISCOUNTsavingsAmountstringThe amount reduced from original payment1000.00
COIN_REDEMPTIONsavingsAmountstringThe amount reduced from original payment1000.00
FEE_WAIVERfeeAmountAfterWaivedstringThe fee value after the waiver is applied1000.00

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
20011002001100SuccessfulResume the next action, such as Payment Request
40011014001101No Eligible ChannelRetry the request or create new request
40011014001101Payment Limit HitFail the request and retry with different payment amount
40011014001101Invalid Access Token LengthFail the request and retry with the proper value
40011024001102
  • Invalid Mandatory Field {merchantId}
  • Invalid Mandatory Field {accountToken}
  • Invalid Client Auth Code
  • Empty Merchant Host ID
  • Empty Client Key
  • Empty Request
  • Empty 'Authorization-Customer' header in API request
  • Empty Merchant External ID
  • Empty Store External ID
  • Empty Access Token
  • Empty Amount
  • Empty Currency
  • Invalid Merchant External ID Length
  • Invalid Store External ID Length
  • Invalid Return URL Length
  • Invalid JSON string
  • Non Positive Amount
  • Currency Non Positive Amount
  • Invalid Currency
  • Currency Not Supported
  • Currency Has No Cents
  • Amount Too Large
  • Invalid Token
  • Invalid Parameter
Fail the request and retry with the proper value
40011024001102
  • Invalid Merchant Host Status
  • Invalid Merchant Status
  • Invalid Store Status
  • Invalid Merchant Product Code
  • Invalid Store Product Code
Fail the request and Contact Shopeepay to check merchant/store status
40111004011100Unauthorized. Invalid TokenUser's token status should be active (Invalid / Inactive)
40111004011100Unauthorized. Account token in API header does not match in API bodyFail the request and retry with the proper value
40111014011101Invalid B2B TokenFail the request and retry with the proper value
40111024011102Unauthorized. Account Token is not valid for this merchantFail the request and retry with the proper value
40311014031101Feature Not AllowedFail the request and Contact Shopeepay to check the merchant's configuration
40311054031105
  • 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
  • User Status Frozen
Fail the request
40311054031105Invalid Field Format {mobileNumber}. User Is Not FoundFail the request and retry with the proper value
40311054031105Permission DeniedFail the request and Contact Shopeepay to check merchant/store status
40411114041111
  • Account Information Invalid
  • Application Not Found
  • Merchant Store Not Found
Fail the request and retry with the proper value
40411134041113Invalid Amount. Currency Does Not Support CentsFail the request and retry with the proper value
50011015001101
  • Get Application Detail Error
  • Get Entity Product Detail Error
Fail the request and retry with the proper value
50411005041100TimeoutCreate new request

Specification

The following table is the specification of the API:

HTTP MethodPOST
Service Code54
Path.../v1.1/debit/payment-host-to-host
Versionv1.1

Request Parameter

•partnerReferenceNostringRequired

Unique identifier of payment transaction generated by merchant.

•merchantIdstringRequired

Unique identifier of merchant in merchant system.

  • Accepts up to 64 characters.
•externalStoreIdstringRequired

Unique identifier of store in merchant system.

  • Accepts up to 64 characters.
•amountObjectRequired
•validUpTostringOptional
  • 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.
•urlParamsArray of ObjectsRequired

Array of object.

•payOptionDetailsArray of Objects

Object containing the details of the selected payment method for the transaction.

•additionalInfoObjectConditional

Response Parameters (When Payment Verification is Required)

•responseCodestring

Error code to specify the error returned.

•responseMessagestring

Debug message to provide more information from response code.

•referenceNostring

Order identifier in ShopeePay system.

•webRedirectUrlstring

The URL for the Client's front-end to redirect to for PIN / OTP verification / SPayLater Agreement page. Only applicable if additional verification / user's acknowledgement is needed.

Note: After the user completes payment verification on the ShopeePay webpage, they will be redirected to your specified return_url. If the payment fails, a fail_reason query parameter will be appended to the return_url to indicate the reason for the failure.

Possible values for fail_reason is outlined on the table below:

fail_reasonDefinition
ERROR_INTERNAL_ERRORPayment Failed with unknown error / ShopeePay internal timeout
DECLINED_VERIFICATION_FAILEDThe payment authentication was not executed, or it did not execute successfully
DECLINED_INSUFFICIENT_BALANCEWallet balance, or Credit balance or Bank Account is insufficient
DECLINED_SUSPICIOUSPayment failed due to a suspicious payment transaction
DECLINED_LIMIT_EXCEEDEDPayment amount Limit is exceeded

Response Parameters (When Payment Verification is Not Required)

•responseCodestring

Error code to specify the error returned.

•responseMessagestring

Debug message to provide more information from response code.

•partnerReferenceNostring

Unique identifier of payment transaction generated by Client.

•referenceNostring

Order identifier in ShopeePay system.

•additionalInfoObject

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
20054002005400SuccessfulMark LnP (Link&Pay) generate process to Success. Forward customer to Shopeepay page
40054004005400Bad RequestMark LnP (Link&Pay) generate process to Failed. Retry request with proper parameter
40054014005401
  • 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
40054024005402
  • 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
40154004015400
  • Unauthorized. Invalid Client Key
  • Unauthorized.{error message}
Mark LnP (Link&Pay) generate process to Failed. Retry request with proper parameter
40154014015401Invalid TokenMark LnP (Link&Pay) generate process to Failed. Retry request with proper parameter
40354014035401
  • 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
40354064035406Feature Not Allowed. Service Is Temporarily Down For Scheduled MaintenanceMark LnP (Link&Pay) generate process to Failed. Retry request periodically or consult to Shopeepay
40454084045408
  • 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
40454134045413Invalid Amount. Currency Does Not Support CentsMark LnP (Link&Pay) generate process to Failed. Retry request with proper parameter
40454184045418Inconsistent RequestMark LnP (Link&Pay) generate process to Failed. Retry request with proper parameter
40954004095400ConflictMark LnP (Link&Pay) generate process to Failed. Retry request periodically or consult to Shopeepay
50054005005400General ErrorMark LnP (Link&Pay) generate process to Failed. Retry request periodically or consult to Shopeepay
50054015005401Internal Server ErrorMark LnP (Link&Pay) generate process to Failed. Retry request periodically or consult to Shopeepay
50454005045400TimeoutMark LnP (Link&Pay) generate process to Failed. Retry request periodically or consult to Shopeepay

Check Transaction Status for Link&Pay

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 MethodPOST
Service Code55
Path.../v1.0/debit/status
Versionv1.0

Request Parameter

•originalPartnerReferenceNostringRequired

Unique identifier of the transaction merchant would like to query, which could be partnerReferenceNo or partnerRefundNo.

•merchantIdstringRequired

Unique identifier of merchant in merchant system.

•externalStoreIdstringRequired

Unique identifier of store in merchant system.

•serviceCodestringRequired

Service code of original transaction, which could be 54 (Link and Pay transaction) or 58 (refund).

•amountObjectRequired

Response Parameter

•responseCodestringRequired

Error code to specify the error returned.

•responseMessagestringRequired

Debug message to provide more information.

•originalReferenceNostring

Transaction identifier in ShopeePay system that is shown to the customer.

The value will be returned for successful payment.

•originalPartnerReferenceNostringOptional

Unique identifier of the transaction merchant would like to query, which could be partnerReferenceNo or partnerRefundNo.

•serviceCodestringRequired

Service code of original transaction, which could be 54 (Link and Pay transaction) or 58 (refund).

•latestTransactionStatusstringRequired

Refer to Transaction Status for specific transaction statuses.

•transAmountObjectOptional
•paidTimestring

Update time of the individual transaction.

Using ISO-8601 timestamp format.

•additionalInfoObjectOptional

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
20055002005500SuccessfulMark LnP (Link&Pay) payment to corresponding status according to response.additionalInfo.latestTransactionStatus. Retry request periodically if didn't get final status
40055004005500Bad RequestMark LnP (Link&Pay) payment to Pending. Retry request with proper parameter
40055014005501
  • 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
40055014005501Invalid Field FormatMark LnP (Link&Pay) payment to Pending. Retry request with proper parameter
40055024005502
  • 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
40055084005508Invalid Field format Invalid MerchantMark LnP (Link&Pay) payment to Pending. Retry request periodically or consult to Shopeepay
40155004015500Unauthorized invalid client key Unauthorized.{error message}Mark LnP (Link&Pay) payment to Pending. Retry request with proper parameter
40155014015501Invalid TokenMark LnP (Link&Pay) payment to Pending. Retry request with proper parameter
40355084035508
  • 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
40455014045501Transaction not foundMark LnP (Link&Pay) payment to Failed
40455084045508Entity not foundMark LnP (Link&Pay) payment to Pending. Retry request periodically or consult to Shopeepay
40455134045513
  • 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
40955004095500ConflictMark LnP (Link&Pay) payment to Pending. Retry request periodically or consult to Shopeepay
50055005005500General ErrorMark LnP (Link&Pay) payment to Pending. Retry request periodically or consult to Shopeepay
50055015005501Internal Server ErrorMark LnP (Link&Pay) payment to Pending. Retry request periodically or consult to Shopeepay
50455005045500TimeoutMark 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 MethodPOST
Service Code58
Path../v1.0/debit/refund
Versionv1.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 MethodPOST
Service Code56
Path.../v1.0/debit/notify
Versionv1.0

Refer to Notify Transaction Status endpoint for the detail request body and Response Parameters.