---
title: "Create Gkash web payment with recurring type"
method: POST
path: "/payment/gkash/create"
tags: ["payment"]
---

# Create Gkash web payment with recurring type

`POST /payment/gkash/create`

Initiate a new Gkash payment transaction with recurring type parameter. This endpoint:
    - Creates a payment record in the database
    - Generates payment form data with recurringtype parameter
    - Returns a payment URL (redirectUrl) and formData for redirecting the customer to Gkash payment page
    - Upon successful payment completion, Gkash will send a callback with an epkey
    - The epkey can be used for future recurring payments without requiring the customer to enter card details again
    
    **Recurring Types:**
    - ANNUAL: For annual subscriptions
    - MONTHLY: For monthly subscriptions
    - WEEKLY: For weekly subscriptions
    - DAILY: For daily subscriptions
    
    **Flow:**
    1. Call this endpoint to create payment
    2. Redirect customer to the returned redirectUrl with formData
    3. Customer completes payment on Gkash page
    4. Gkash sends callback to your callbackUrl with epkey
    5. Use the epkey in recurring payment endpoint for future charges
    
    **How to Redirect to Payment Page:**
    
    After receiving the response, you need to create a form and auto-submit it:
    
    ```javascript
    // JavaScript example
    if (response.data.redirectUrl && response.data.formData) {
      const form = document.createElement('form');
      form.method = 'POST';
      form.action = response.data.redirectUrl;
      
      // Add all form fields
      Object.keys(response.data.formData).forEach(key => {
        const input = document.createElement('input');
        input.type = 'hidden';
        input.name = key;
        input.value = response.data.formData[key];
        form.appendChild(input);
      });
      
      document.body.appendChild(form);
      form.submit(); // Redirects to Gkash payment page
    }
    ```
    
    See examples/gkash-payment-redirect-example.js for complete implementation.

## Request body

- CreateGkashPaymentDto
  - `transactionType` 'RELOAD' | 'PURCHASE' | 'SUBSCRIPTION' | 'TOPUP' | 'OTHER', required — Transaction type
  - `amount` string, required — Payment amount (min 1.00)
  - `currency` string, required — Currency code
  - `prodDesc` string, required — Product description
  - `userName` string, required — User name
  - `userEmail` string, required — User email
  - `userContact` string, required — User contact number
  - `recurringType` 'ANNUAL' | 'MONTHLY' | 'WEEKLY' | 'DAILY', required
  - `returnUrl` string — Frontend return URL
  - `callbackUrl` string — Backend callback URL for payment status updates
  - `refNo` string — Reference number (cart ID) - auto-generated if not provided
  - `memberID` string — Member ID
  - `walletID` string — Wallet ID
  - `documentID` string — Document ID
  - `remark` string — Remark
  - `v_billemail` string — Billing email (v_billemail) - Email address for billing. If not provided, userEmail will be used.
  - `v_billphone` string — Billing phone (v_billphone) - Phone number for billing. If not provided, userContact will be used.

## Response `201`

Gkash payment created successfully. Response includes redirectUrl and formData for redirecting customer to Gkash payment page.

- CreatePaymentResponseDto
  - `success` boolean, required — Success indicator
  - `message` string, required — Message
  - `data` PaymentResponseDto, required
    - `paymentId` number, required — Payment ID
    - `refNo` string, required — Reference number (exactly 20 characters)
    - `status` 'pending' | 'processing' | 'success' | 'failed' | 'cancelled', required — Payment status
    - `amount` number, required — Amount
    - `currency` string, required — Currency
    - `transactionType` string, required — Transaction type
    - `ipay88TransId` string — iPay88 Transaction ID
    - `ipay88AuthCode` string — iPay88 Authorization Code
    - `ipay88Status` string — iPay88 Status Code
    - `errorDescription` string — Error description if failed
    - `tokenId` string — Token ID for future payments
    - `cardDetails` CardDetailsDto
      - `last4` string, required — Last 4 digits of card
      - `cardType` string, required — Card type
      - `cardHolderName` string, required — Card holder name
      - `expiryMonth` string, required — Expiry month
      - `expiryYear` string, required — Expiry year
      - `issuingBank` string, required — Card issuing bank
      - `issuingCountry` string, required — Card issuing country
    - `memberId` string — Member ID
    - `walletId` string — Wallet ID
    - `remark` string — Remark
    - `createdAt` string, date-time, required — Created timestamp
    - `updatedAt` string, date-time, required — Updated timestamp
    - `completedAt` string, date-time — Completed timestamp
    - `redirectUrl` string — Redirect URL for initial payment (if no token)
    - `formData` object — Form data for payment page submission (if no token)
    - `epkey` string — Gkash epkey for recurring payments
    - `gkashStatus` string — Gkash status
    - `gkashTransId` string — Gkash transaction ID (POID)
    - `gkashPaymentType` string — Gkash payment type

## Other responses

- `400` — Bad request - invalid payment data (e.g., amount less than 1.00, invalid format)
- `500` — Internal server error

---

[API](https://skmtc.dev/tonewow/apis/tonewow-database-api.md) · [All operations](https://skmtc.dev/tonewow/apis/tonewow-database-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/tonewow/tonewow-database-api/revisions/f36472974ad4/schema)