---
title: "Create Payment Request"
method: POST
path: "/v1/payment-requests"
---

# Create Payment Request

`POST /v1/payment-requests`

This endpoint creates a new payment request. This is the first step of the payment flow, once you have all the details from the user and are ready to collect payment use this API to create a payment request.
Since this is a server-to-server communication, if you have a mobile or Web client that communicates with your REST API, you must have a new endpoint E.g. /create-order, or reuse an existing endpoint. This endpoint will be responsible for making the payment request API call to HitPay.

## Headers

- `X-BUSINESS-API-KEY` string, required

## Request body

- object
  - `amount` number, double, required — It's required field. Amount related to the payment. Example: 2500
  - `currency` string, required — It's required field. Currency related to the payment.
  - `payment_methods` string[] — They're available payment methods supported on your account.(Example: paynow_online , card, wechat, alipay, grabpay_direct, grabpay_paylater, shopee_pay ... etc.). If we don't pass, use the available methods
  - `email` string, email — Buyer’s email
  - `name` string — Buyer’s name
  - `phone` string, phone — Buyer’s phone number
  - `wifi_terminal_id` string — It's terminal id and it's required if payment method is wifi_card_reader
  - `staff_id` string, uuid — It's active staff id from the dashboard
  - `location_id` string, uuid — The active location belongs to business. Support both `location_id` and `business_location_id` for backward compatibility, but we recommend using `business_location_id` for future use.
  - `business_location_id` string, uuid — The active location belongs to business.
  - `purpose` string — Purpose of the Payment request.
  - `reference_number` string — Arbitrary reference number that you can map to your internal reference number. This value cannot be edited by the customer
  - `redirect_url` string, uri — URL where we redirect the user after a payment. Query arguments reference (payment request id) and status are sent along
  - `webhook` string, uri — URL where our server do POST request after a payment If done
  - `allow_repeated_payments` 'true' | 'false' — If set to true, multiple payments can be paid on a payment request link. Default value is false
  - `expiry_date` string — Time after which the payment link will be expired (time in SG with YYYY-MM-DD HH:mm:ss format). Applicable for repeated payments.
  - `expires_after` string — E.g "30 mins" Other supported keys are "mins", "hours", "days"
  - `add_admin_fee` 'true' | 'false' — If set to true, the admin fee will be included in total.
  - `send_email` 'true' | 'false' — It's "true" or "false". If set to true, an email receipt will be sent to the customer after the payment is completed. Default is false
  - `send_sms` 'true' | 'false' — It's "true" or "false". If set to "true", SMS will be sent to the customer after the payment is completed. Default is false
  - `address` object
    - `line1` string, required
    - `line2` string
    - `city` string, required
    - `country` string, required
    - `state` string, required
    - `postal_code` string, required
  - `generate_qr` boolean — Only valid for paynow_online, qrph_netbank, doku_qris and shopee_pay if generate_qr was true
  - `metadata` object — Support the key-value. The value must be string type, and the max length of the value is 500 characters, up to 50 key-value. Example: {"car_model": "toyota", "car_color": "red"}
    - `key` string

## Response `200`

200

- object
  - `id` string
  - `name` string
  - `email` string
  - `phone` string
  - `amount` string
  - `currency` string
  - `status` 'pending' | 'completed' | 'failed' | 'expired' | 'canceled' | 'inactive'
  - `purpose` string
  - `reference_number` string
  - `payment_methods` string[]
  - `url` string
  - `redirect_url` string
  - `webhook` string
  - `send_sms` boolean
  - `send_email` boolean
  - `sms_status` string
  - `email_status` string
  - `allow_repeated_payments` boolean
  - `expiry_date` string
  - `created_at` string
  - `updated_at` string
  - `staff_id` string, nullable
  - `business_location_id` string, nullable
  - `metadata` object
    - `key` string

## Other responses

- `422` — 422

---

[API](https://skmtc.net/hitpayapp/apis/hitpay-api.md) · [All operations](https://skmtc.net/hitpayapp/apis/hitpay-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/hitpayapp/hitpay-api/revisions/6aae1a736990/schema)