ShopeePay

Trusted Redirects Bundle

ShopeePay is one of the most widely used digital wallets in Indonesia, available to customers inside the Shopee and ShopeePay apps as well as on the web. Customers pay with their ShopeePay wallet balance and, when the merchant is enabled for it, with ShopeePayLater. Payments are collected in Indonesian Rupiah (IDR) and confirmed in real time, which makes ShopeePay a strong alternative to cards for e-commerce, gaming, digital goods, and everyday retail purchases in Indonesia.

This guide walks you through integrating ShopeePay via API, covering how to create a payment, redirect the customer, handle the payment result, refund a transaction, and monitor status changes.

Requirements

• API authentication - All API requests must be authenticated using JWS (JSON Web Signature). The legacy integration_key is being deprecated — if you still use it, follow the Migration Guide to transition to JWS. If you don't have credentials yet, complete the Merchant Signup Form.
• Familiarity with EBANX Direct - This setup follows the same general structure as other payment methods, with a few unique parameters. See EBANX Direct for more info.
• ShopeePayLater (optional) - The ShopeePay wallet balance is the default source of funds. ShopeePayLater requires prior approval from ShopeePay, and merchants enabled for it must also support the refund flow described in this guide.

How it works

ShopeePay does not require account binding. After the customer chooses ShopeePay, EBANX creates the payment and returns a redirect URL to the ShopeePay environment, where the customer authorizes the transaction. The customer can pay with either of two sources of funds:

• ShopeePay wallet balance.
• ShopeePayLater, subject to additional approvals.

Mobile flow

1. The customer chooses ShopeePay as their payment method.
2. The merchant requests a ShopeePay payment with EBANX.
3. EBANX returns a redirect URL in the response payload.
4. The merchant redirects the customer to this URL, which opens the ShopeePay app.
5. The customer authenticates and confirms the payment in the app.
6. The customer returns to the merchant page, and the merchant receives a notification from EBANX.

Web flow

1. The customer chooses ShopeePay as their payment method.
2. The merchant requests a ShopeePay payment with EBANX.
3. EBANX returns a redirect URL in the response payload.
4. The merchant redirects the customer to the ShopeePay checkout page.
5. The customer authenticates and confirms the payment on the ShopeePay page.
6. The customer returns to the merchant page, and the merchant receives a notification from EBANX.

Technical flow

• Request payment - Call the ws/direct endpoint with the parameters defined below.

• Payment instructions - EBANX returns a redirect_url that leads to the ShopeePay environment. The merchant must redirect the customer to it.

• Customer completes the payment - The customer has 10 minutes to complete the transaction. During this window, the payment stays pending (PE) on the EBANX platform.

• Payment confirmation - Once ShopeePay confirms the payment, the status changes to confirmed (CO). If the customer does not complete it within the window, the payment is canceled (CA).

• EBANX notification - EBANX sends a webhook notification on every status change, so you can fulfill the order.

• Learn more about Payment Notificationschevron_right
• Learn more about Retrieving Payment Statuschevron_right

Instructions

Follow the steps below.

1. Select your environment

   Select the appropriate environment for your integration. Use the sandbox environment for testing or the production environment for live transactions.

   Select the appropriate environment for your integration. Use the sandbox environment for testing, or the production environment for live transactions. Use the URL for your HTTP requests based on your selection.

   Check the method's availability for your country and tenant in Payment Methods by Country. Questions about tenant and environment? Check our API Operability and API Endpoints.

   Cross-border sandbox

   https://sandbox.ebanxpay.com/ws/direct

2. Define your parameters

   
   

   Defining API parameters

   You must provide required parameters for payment requests. These parameters ensure successful completion of transactions.
   
   

   Essential parameters

   • payment.payment_type_code - Specifies the payment method to be used for the transaction.
   • payment.currency_code - Three-letter code of the payment currency
   • payment.amount_total - Total amount to be charged.

   
   

   Additional parameters

   • EBANX Integration Key - Used to authenticate and authorize API requests.
   • Customer Information
     • Includes details such as the customer name, email, address and document number (Depends on the requirements of the payment method or local regulations).
     • While not mandatory for all countries or payment methods, providing this information can enhance security and increase the likelihood of successful processing.
   • Additional Context - Extra data for specific methods or countries.

   
   

   To learn more about API parameters, please refer to the

   API Reference Guide chevron_right

   
   

   The following tables outline the key parameters specific to ShopeePay.

   Basic parameters

   Parameter	Requirement	Description
   integration_key	Required	Your EBANX integration key
   payment_type_code	Required	Set to shopee-pay
   country	Required	Set to id for Indonesia

   Customer data

   Parameter	Requirement	Description
   name	Required	Customer name
   email	Required	Customer email
   phone_number	Optional	Customer phone number

   Charge parameters

   Parameter	Requirement	Description
   merchant_payment_code	Required	Unique merchant payment code
   currency_code	Required	Supported value: IDR
   amount_total	Required	Total amount to be charged
   redirect_url	Required	Merchant URL the customer returns to after finishing the payment on ShopeePay

   Minimum and maximum amounts

   • Minimum amount: IDR 1.
   • The maximum amount follows the customer's ShopeePay wallet limits: up to IDR 2,000,000 for non-verified users and up to IDR 20,000,000 for verified (KYC) users.
   Payment expiration

   The payment link is valid for 10 minutes. After that, the payment is canceled automatically.

3. Create payment request

   Once your customer submits a ShopeePay payment, create a payment request using the ws/direct endpoint. Assign the payment_type_code parameter to shopee-pay.

   
   

   Sample request

   Shell

   curl -X POST \
     --location 'https://sandbox.ebanxpay.com/ws/direct' \
     --header 'Content-Type: application/json' \
     --data '{
       "integration_key": "{{integration_key}}",
       "payment": {
           "name": "John Doe",
           "email": "john.doe@example.com",
           "country": "id",
           "payment_type_code": "shopee-pay",
           "redirect_url": "https://merchant.example.com/callback",
           "merchant_payment_code": "{{unique_merchant_code}}",
           "currency_code": "IDR",
           "amount_total": 99.85
       }
   }'

4. Payment successful response

   Each request returns a response similar to the example below.

   JSON

   {
     "redirect_url": "{{redirect_url}}",
     "payment": {
       "hash": "59acc5f00945fa382ab051651440826da7701533249b3a475",
       "country": "id",
       "merchant_payment_code": "{{unique_merchant_code}}",
       "order_number": null,
       "status": "PE",
       "status_date": "{{YYYY-MM-DD HH:mm:ss}}",
       "open_date": "{{YYYY-MM-DD HH:mm:ss}}",
       "confirm_date": null,
       "transfer_date": null,
       "amount_br": "99.85",
       "amount_ext": "99.85",
       "amount_iof": "1",
       "currency_rate": "1",
       "currency_ext": "IDR",
       "due_date": "{{YYYY-MM-DD}}",
       "instalments": "1",
       "payment_type_code": "shopee-pay",
       "pre_approved": false,
       "capture_available": null,
       "redirect_url": "{{redirect_url}}"
     },
     "status": "SUCCESS"
   }

   At this stage, the payment will appear as pending (PE) in your

   Merchant Areachevron_right
   
   
   redirect_url behavior

   Note that the address returned from EBANX in redirect_url on the response (the address to which the customer must be redirected to continue with the transaction within the ShopeePay environment) is different from the redirect_url specified by the merchant in the transaction request (the address to which the customer will be redirected at the end of the transaction).

5. Redirect customer to ShopeePay

   Redirect the customer to the redirect_url from the response. On mobile, the ShopeePay app opens when it is installed. On a web browser, the ShopeePay checkout page opens.

   Link expiration

   The redirect link expires after 10 minutes. Make sure the customer completes the payment within this window.

   Sandbox behavior

   When testing in sandbox, a simulator environment will be rendered to accept or decline the payment.

6. Monitor payment for status changes

   Notifications

   • EBANX will send a notification whenever a payment status changes.
   • Make sure your system is set up to receive notifications from EBANX for any changes in payment status.
   • Learn more about Payment Notificationschevron_right

   Status

   • After receiving a notification, retrieve the payment status.
   • When a payment is confirmed, the status changes from pending (PE) to confirmed (CO). If the customer does not complete the payment within 10 minutes, the status changes to canceled (CA).
   • Learn more about Retrieving Payment Statuschevron_right

7. Congratulations!

   You have successfully integrated ShopeePay.

   For more information, refer to the

   Direct API reference guidechevron_right

Refunds

ShopeePay supports full and partial refunds through the EBANX refund flow. To initiate a refund, call the ws/refund endpoint with operation set to request, the original payment hash, the amount to refund, a description, and a unique merchant_refund_code.

Rule	Detail
Eligible payments	Only payments confirmed (CO) by ShopeePay
Refund type	Both partial and full refunds are supported
Refund window	365 days from the payment date
Failed or canceled payments	Cannot be refunded

Refunds may stay pending

For payments made with the ShopeePay wallet balance, the refunded amount cannot push the customer's wallet above its balance limit (IDR 2,000,000 for non-verified users, IDR 20,000,000 for verified users). If the limit is reached, the refund is accepted but stays pending on the ShopeePay side and is processed automatically once the balance allows it. Do not resubmit the refund request in this scenario.

Behavior to expect

These behaviors were observed while validating the integration and are useful when handling failure scenarios.

Scenario	Behavior
Insufficient wallet balance	The payment is not declined immediately: the customer can top up and retry within the 10-minute window. If they do not, the payment expires and EBANX reports it as canceled (CA).
Customer closes the ShopeePay app without confirming	The payment stays pending until the 10-minute window ends, then expires and is reported as canceled (CA).
Payment session expires	The provider notification carries a failed transaction status, and EBANX moves the payment to canceled (CA).
Amount formatting	The exact amount is displayed in the ShopeePay app in IDR.

Resources

Use the following resources when testing in your sandbox environment.

API Reference

Click here to access detailed API documentation to integrate efficiently.

Click to explorechevron_right

Mock Customer Data

Click here to view mock customer data for testing and validating user flows.

Click to explorechevron_right

Error Codes

Click here to review common error codes to troubleshoot and resolve issues quickly.

Click to explorechevron_right

Still need help?

We hope this article was helpful. If you still have questions, you can explore the following options:

• Merchant support: Contact our support team at sales.engineering@ebanx.com for assistance.
• Not a partner yet? Please complete the Merchant Signup Form, and our commercial team will reach out to you.