# GrabPay

## Introduction

GrabPay is a digital wallet and payment solution provided by Grab, widely used across Southeast Asia. It allows users to make payments, transfer money, and manage finances through the Grab app. GrabPay provides a convenient and secure payment experience for merchants and customers in Southeast Asian markets.

| 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:

- Widely used across Southeast Asia
- Fast and convenient payment experience
- Secure wallet-based transactions
- Support for online payments
- Integrated with Grab ecosystem services


## Integration Methods

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

### Hosted Integration

If you use PayKKa's hosted checkout page to integrate GrabPay, you only need to accept GrabPay as a payment method during the merchant onboarding process, and PayKKa will handle all transactions with GrabPay 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": [
    "GRABPAY"
  ]
}
```

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"
  }
}
```

### 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 GrabPay 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": "COMPONENT",
  "display_merchant_name": "PayKKa Merchant",
  "display_locale": "en-PH",
  "allowed_payment_methods": [
    "GRABPAY"
  ]
}
```

## 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"
  }
}
```