# ShopeePay

## Introduction

ShopeePay is a digital wallet payment solution provided by Shopee, supporting online payments. It allows users to make payments through the ShopeePay wallet, providing a convenient and secure payment experience for merchants and customers in Southeast Asia.

| Attribute | Support Status |
|  --- | --- |
| Payment Mode | Wallet |
| Integration Products | Checkout, PaymentLink, Billing |
| Supported Currencies | PHP |
| Payment Flow | Redirect |
| Auto-capture payment | ✅ |
| Authorization | ❌ |
| Capture | ❌ |
| Partial Capture | ❌ |
| Void | ✅ |
| Partial Void | ❌ |
| Refund | ✅ |
| Partial Refund | ✅ |
| Dispute | ❌ |
| Recurring Subscription | ❌ |
| 3DS | ❌ |


It has the following advantages:

- Fast and convenient payment experience
- Widely used in Southeast Asian markets
- Secure wallet-based transactions
- Support for online payments


## Integration Methods

PayKKa provides multiple ways to integrate ShopeePay, and you can choose the appropriate method according to your needs.

### Hosted Integration

If you use PayKKa's hosted checkout page to integrate ShopeePay, you only need to accept ShopeePay as a payment method during the merchant onboarding process, and PayKKa will handle all transactions with ShopeePay behind the scenes. This integration solution is the most convenient.

1. Call the interface [Create Session](/payments/apis/payments/openapi/session/session-opl_1)


```json
{
  "merchant_id": "YOUR_MERCHANT_ID",
  "payment_type": "PURCHASE",
  "trans_id": "t202311081113",
  "currency": "PHP",
  "amount": 1000,
  "session_mode": "HOSTED",
  "display_merchant_name": "PayKKa Merchant",
  "display_locale": "en-PH",
  "allowed_payment_methods": [
    "SHOPEE_PAY"
  ]
}
```

Response Example

```json
{
  "ret_code": "000000",
  "ret_msg": "Success",
  "data": {
    "merchant_id": "YOUR_MERCHANT_ID",
    "trans_id": "t202311081113",
    "session_id": "CS208760010022288125",
    "session_mode": "HOSTED",
    "status": "PROCESSING",
    "currency": "PHP",
    "amount": "1000",
    "session_url": "https://checkout.aq.paykka.com/hp/pay/CS208760010022288125"
  }
}
```

Where `session_mode` field value is specified as `HOSTED`, and `allowed_payment_methods` allows `SHOPEE_PAY`.

### Component Integration

Component is a modular payment integration method, and developers can freely and flexibly choose to combine different payment components as needed. You can add ShopeePay payment elements to your payment page in this way.

1. Introduce PayKKa Checkout UI Component library


For specific usage steps, please refer to [PayKKa Checkout UI Component Usage Documentation - PayKKa Docs for Payments](/payments/docs/developer-resources/checkout-ui-component).

1. Call the interface [Create Session](/payments/apis/payments/openapi/session/session-opl_1)


```json
{
  "merchant_id": "YOUR_MERCHANT_ID",
  "payment_type": "PURCHASE",
  "trans_id": "t202311081113",
  "currency": "PHP",
  "amount": 1000,
  "session_mode": "HOSTED",  # Checkout mode, HOSTED: hosted, DROP_IN: embedded, COMPONENT: component
  "display_merchant_name": "PayKKa Merchant",
  "display_locale": "en-PH",
  "allowed_payment_methods": [
    "SHOPEE_PAY"
  ]
}
```

## Checkout Query

Query checkout status by checkout ID(`session_id`)

Request Example
[Query Session](/payments/apis/payments/openapi/session/session-query-opl_2)

```json
{
  "merchant_id": "YOUR_MERCHANT_ID",
  "trans_id": "m3246749195217",  # trans_id/session_id two choose one
  "session_id": "CS208760010022288125"
}
```

Response Example

Processing
```json
{
  "ret_code": "000000",
  "ret_msg": "Success",
  "data": {
    "merchant_id": "YOUR_MERCHANT_ID",
    "trans_id": "m3246749195217",
    "session_id": "CS208760010022288125",
    "session_mode": "HOSTED",
    "status": "PROCESSING",
    "amount": "800",
    "currency": "PHP",
    "expire_time": "2025-05-05T17:17:24+08:00",
    "session_url": "https://checkout.aq.paykka.com/hp/pay/CS208760010022288125"
  }
}
```

Success
```json
{
  "ret_code": "000000",
  "ret_msg": "Success",
  "data": {
    "merchant_id": "YOUR_MERCHANT_ID",
    "trans_id": "m3246749195217",
    "session_id": "CS208760010022288125",
    "session_mode": "HOSTED",
    "status": "SUCCESS",  # checkout status
    "order_status": "SUCCESS",  # transaction status
    "error_code": "0000", # transaction error code
    "error_description": "request success",
    "order_id": "GW208760010022288125", # transaction order id
    "amount": "800",
    "currency": "PHP",
    "expire_time": "2025-05-05T17:17:24+08:00",
    "session_url": "https://checkout.aq.paykka.com/hp/pay/CS208760010022288125"
  }
}
```

Expired
```json
Payment not initiated before expiration
{
  "ret_code": "000000",
  "ret_msg": "Success",
  "data": {
    "merchant_id": "YOUR_MERCHANT_ID",
    "trans_id": "m3246749195217",
    "session_id": "CS208760010022288125",
    "session_mode": "HOSTED",
    "status": "EXPIRED",  # checkout status
    "amount": "800",
    "currency": "PHP",
    "expire_time": "2025-05-05T17:17:24+08:00"
  }
}

Payment failed
{
  "ret_code": "000000",
  "ret_msg": "Success",
  "data": {
    "merchant_id": "YOUR_MERCHANT_ID",
    "trans_id": "m3246749195217",
    "session_id": "CS208760010022288125",
    "session_mode": "HOSTED",
    "status": "EXPIRED",  # checkout status
    "amount": "800",
    "currency": "PHP",
    "order_status": "FAILURE",  # transaction status
    "error_code": "0000", # transaction error code
    "error_description": "request success",
    "order_id": "GW208760010022288125", # transaction order id
    "expire_time": "2025-05-05T17:17:24+08:00"
  }
}
```

## Transaction Query

Query transaction status by transaction ID(`order_id`)

Request Example
[Query Transaction](/payments/apis/payments/openapi/transaction/payments-query-opl_1)

```json
{
  "merchant_id": "YOUR_MERCHANT_ID",
  "trans_id": "m3246749195217",    # session_id/order_id/trans_id three choose one
  "session_id": "CS208760010022288125",
  "order_id": "GW208760010022288125"
}
```

Response Example

```json
{
  "ret_code": "000000",
  "ret_msg": "Success",
  "data": {
    "merchant_id": "YOUR_MERCHANT_ID",
    "trans_id": "m3246749195217",
    "order_id": "GW208760010022288125",
    "status": "SUCCESS",
    "error_code": "0000",
    "error_description": "request success",
    "amount": "1000",
    "currency": "PHP",
    "pay_finish_time": "2025-05-05T17:17:24+08:00"
  }
}
```