---
title: "Create a payment and get a hosted payment page URL"
method: POST
path: "/v1/payments"
tags: ["external-payments"]
---

# Create a payment and get a hosted payment page URL

`POST /v1/payments`

Creates a payment for the authenticated client and returns `paymentUrl`. Send the customer there; they pay on the gateway page and are redirected to your `returnUrl` with `refNo`, `status`, and `clientReference` query parameters. Treat the redirect as a hint only. The webhook (or GET /v1/payments/{refNo}) is the source of truth.

## Headers

- `idempotency-key` string, required
- `Idempotency-Key` string

## Request body

- CreateExternalPaymentDto
  - `amount` string, required — Amount with up to two decimals
  - `currency` string — ISO 4217 currency
  - `description` string, required — Shown on the gateway page and in reports (max 200 chars)
  - `returnUrl` string, required — Where to send the customer after payment. Must be https and, if the client has an allow-list, match it.
  - `clientReference` string — Your own order / invoice reference. Echoed back on the return redirect and in webhooks.
  - `gateway` 'revpay' | 'gkash' — Gateway to use. Defaults to the client default. Only revpay is available through this API today.
  - `transactionType` 'PURCHASE' | 'RELOAD' | 'SUBSCRIPTION' | 'TOPUP' | 'OTHER'
  - `paymentMethod` string — RevPay Payment_ID (Appendix A). Leave empty to let the customer choose on the RevPay page. 2 = card, 3 = FPX, 28 = Touch n Go.
  - `bankCode` string — RevPay Bank_Code (Appendix B), only meaningful with paymentMethod 3 or 9.
  - `customerName` string
  - `customerEmail` string — Required by RevPay for card payments (paymentMethod 2).
  - `customerContact` string — Required by RevPay for card payments. Format +60123456789.
  - `customerIp` string — Customer's IP as seen by you. If omitted, the IP that opens the hosted page is used.

## Response `201`

- ExternalPaymentResponseDto
  - `refNo` string, required
  - `clientReference` string
  - `gateway` string, required
  - `status` 'pending' | 'processing' | 'success' | 'failed' | 'cancelled' | 'refunded' | 'expired', required
  - `amount` string, required
  - `currency` string, required
  - `description` string, required
  - `paymentUrl` string — Send the customer here. Present while the payment can still be paid.
  - `returnUrl` string, required
  - `gatewayTransactionId` string
  - `bankReference` string
  - `responseCode` string — Raw gateway result code (RevPay Appendix C)
  - `errorDescription` string
  - `paymentMethod` string — RevPay Payment_ID actually used
  - `refundedAmount` string, required
  - `createdAt` string, date-time, required
  - `completedAt` string, date-time

## Other responses

- `400` — Validation error, disallowed return URL, or unsupported gateway
- `401` — Invalid or missing API key

## Changes

- **2026-09-17** `f7cc9325b5b7` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/tonewow/apis/tonewow-database-api/changes/v1/payments/post.md)

---

[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.dev/tonewow/apis/tonewow-database-api/revisions/60d5bbdc852a?raw)