---
title: "Create a new payment"
method: POST
path: "/payment/create"
tags: ["payment"]
---

# Create a new payment

`POST /payment/create`

Initiate a new payment transaction with iPay88. Supports both initial payment (redirect to iPay88) and subsequent charge (using saved token).

## Request body

- CreatePaymentDto
  - `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
  - `responseURL` string — Frontend success/failure callback URL
  - `backendURL` string — Backend callback URL for payment status updates
  - `refNo` string — Reference number (auto-generated if not provided, exactly 20 characters)
  - `documentID` string — Document ID
  - `memberID` string — Member ID
  - `extraCharges` string — Extra charges
  - `isToken` string — Use saved token (1 = yes, 0 = no)
  - `walletID` string — Wallet ID
  - `channelCode` string — Channel code
  - `productId` string — Product ID
  - `remark` string — Remark
  - `creditTranDetailType` string — Credit transaction detail type
  - `memberIDDesc` string — Member ID description
  - `msisdn` string — MSISDN (phone number)
  - `transferRef` string — Transfer reference

## Response `201`

Payment created successfully. For initial payment, redirectUrl and formData will be provided. For subsequent charge, payment status will be returned.

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