ShopeePay Philippines Digital Wallet Integration Guide

ShopeePay is a digital wallet in the Philippines that allows customers to pay online using their wallet balance, ShopeePay BNPL, or Maribank. By integrating ShopeePay, merchants can offer a local payment option for customers in the Philippines, providing an alternative to card payments. This method supports both mobile and web browser flows through PayMongo. This guide outlines the key concepts and implementation details required to integrate ShopeePay via API. It covers essential steps such as initiating payments, redirecting customers, and monitoring payment status.

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.

How it works

If the customer is paying on a mobile device, the ShopeePay app flow opens automatically. If using a web browser, the customer completes the payment on a ShopeePay web page.

Mobile Flow

The customer chooses ShopeePay as their payment method.
The merchant requests a ShopeePay transaction with EBANX.
EBANX returns a redirect URL in the response payload.
The merchant redirects the customer to this URL.
The customer is redirected to the ShopeePay app.
The customer authenticates and confirms the payment in the ShopeePay app.
The customer is redirected back to the merchant's site after payment confirmation.

Web Flow

The customer chooses ShopeePay as their payment method.
The merchant requests a ShopeePay transaction with EBANX.
EBANX returns a redirect URL in the response payload.
The merchant redirects the customer to this URL.
The customer authenticates and confirms the payment on a ShopeePay web page.
The customer is redirected back to the merchant's site after payment confirmation.

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 PayMongo checkout page.
Customer completes the payment - Once the redirect URL is accessed, the customer has 10 minutes to complete the transaction. During this time, the transaction remains pending (PE).
Payment confirmation - Once the customer completes the payment, EBANX updates the status to confirmed (CO) or canceled (CA). The merchant receives a notification and can query the final status through ws/query.
Learn more about Payment Notifications
Learn more about Retrieving Payment Status

Instructions

Follow the steps below.

Select your environment

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.
SandboxProduction
https://sandbox.ebanx.com/ws/direct

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

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 `ph` for Philippines

Customer data

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

Address parameters

Parameter	Requirement	Description
`city`	Optional	Customer city
`zipcode`	Optional	Customer postal code

Charge parameters

Parameter	Requirement	Description
`merchant_payment_code`	Required	Unique merchant payment code
`currency_code`	Required	Supported value: `PHP`
`amount_total`	Required	Total amount to be charged
`redirect_url`	Required	Merchant URL to redirect the customer after payment

ShopeePay has a minimum amount limit of 1 PHP and a maximum amount limit of 100,000 PHP.

ShopeePay payments can be refunded within 365 days.

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

curl -X POST 'https://sandbox.ebanx.com/ws/direct' \
  -H 'Content-Type: application/json' \
  -d '{
    "integration_key": "{{integration_key}}",
    "payment": {
      "name": "John Doe",
      "email": "john.doe@example.com",
      "country": "ph",
      "phone_number": "5555555555",
      "city": "Capital City",
      "zipcode": "00000",
      "payment_type_code": "shopee-pay",
      "merchant_payment_code": "{{unique_merchant_code}}",
      "currency_code": "PHP",
      "amount_total": 99.85,
      "redirect_url": "https://merchant.example.com/callback"
    }
  }'

Payment successful response

Each request returns a response similar to the example below.

{
  "payment": {
    "hash": "59acc5f00945fa382ab051651440826da7701533249b3a475",
    "country": "ph",
    "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": "PHP",
    "due_date": "{{YYYY-MM-DD}}",
    "instalments": "1",
    "payment_type_code": "shopee-pay",
    "redirect_url": "https://sandbox.ebanx.com/ws/redirect?hash=59acc5f00945fa382ab051651440826da7701533249b3a475",
    "pre_approved": false,
    "capture_available": null,
    "customer": {
      "email": "john.doe@example.com",
      "name": "John Doe"
    }
  },
  "status": "SUCCESS",
  "redirect_url": "https://sandbox.ebanx.com/ws/redirect?hash=59acc5f00945fa382ab051651440826da7701533249b3a475"
}

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

Merchant Area

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).

Redirect customer to ShopeePay

Redirect the customer to the redirect_url from the response. On mobile, the ShopeePay app opens when available. On a web browser, the ShopeePay checkout page opens.
Payment expiration
The customer has 10 minutes to complete the payment after the redirect. If the timeout is reached, the payment will be automatically canceled.
Sandbox behavior
When testing in sandbox, a simulator environment will be rendered, allowing merchants to accept or decline the payment without direct communication with ShopeePay.
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 Notifications
Status
- After receiving a notification, retrieve the payment status.
- When a payment is confirmed, the status will change from pending (PE) to confirmed (CO). If the customer does not complete the payment, the status will automatically update to canceled (CA).
- Learn more about Retrieving Payment Status
Congratulations!

You have successfully integrated ShopeePay.
For more information, refer to the
Direct API reference guide

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 explore

Mock Customer Data

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

Click to explore

Error Codes

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

Click to explore

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.

ShopeePay

Requirements​

How it works​

Mobile Flow​

Web Flow​

Technical flow​

Instructions​

Select your environment​

Define your parameters​

Basic parameters​

Customer data​

Address parameters​

Charge parameters​

Create payment request​

Payment successful response​

Redirect customer to ShopeePay​

Monitor payment for status changes​

Congratulations!​

Resources​

API Reference

Mock Customer Data

Error Codes

Still need help?

Requirements

How it works

Mobile Flow

Web Flow

Technical flow

Instructions

Select your environment

Define your parameters

Basic parameters

Customer data

Address parameters

Charge parameters

Create payment request

Payment successful response

Redirect customer to ShopeePay

Monitor payment for status changes

Congratulations!

Resources