Create Payment Request

Create a payment request to collect payments via cards, PayNow, FPX, GrabPay, and other methods

POST /v1/payment-requests

Create Payment Request

cURL

curl --request POST \
  --url https://api.hit-pay.com/v1/payment-requests \
  --header 'Content-Type: application/json' \
  --header 'X-BUSINESS-API-KEY: <x-business-api-key>' \
  --data '
{
  "currency": "SGD",
  "amount": 100,
  "payment_methods": [
    "card"
  ],
  "email": "[e-mail]",
  "name": "<string>",
  "phone": "<string>",
  "wifi_terminal_id": "<string>",
  "staff_id": "98888a24-d6b2-430d-9063-d2be76d443cd",
  "location_id": "9dd07721-d215-4947-9c79-2b8ec25f69db",
  "business_location_id": "9dd07721-d215-4947-9c79-2b8ec25f69db",
  "purpose": "<string>",
  "reference_number": "<string>",
  "redirect_url": "https://www.google.com",
  "webhook": "https://www.google.com",
  "allow_repeated_payments": "false",
  "expiry_date": "<string>",
  "expires_after": "5 minutes",
  "send_email": "false",
  "send_sms": "true",
  "generate_qr": false,
  "metadata": {
    "key": "<string>"
  }
}
'

200

{
  "id": "9ef68e2e-3569-4f69-9f68-04c7e4bb007c",
  "name": "Harvey Friesen",
  "email": "[e-mail]",
  "phone": "[phone]",
  "amount": "10.00",
  "currency": "sgd",
  "is_currency_editable": false,
  "status": "pending",
  "purpose": "Purpose_1747817845",
  "reference_number": "1747817845",
  "payment_methods": [
    "card"
  ],
  "url": "https://securecheckout.sandbox.hit-pay.com/payment-request/@qasg/9ef68e2e-3569-4f69-9f68-04c7e4bb007c/checkout",
  "redirect_url": "https://google.com",
  "webhook": "https://webhook.site/8cbdef58-cd15-441a-986d-9446235223ea",
  "send_sms": true,
  "send_email": true,
  "sms_status": "pending",
  "email_status": "pending",
  "allow_repeated_payments": false,
  "expiry_date": "2025-05-26T15:10:00",
  "address": {
    "line1": "177 River Valley Road",
    "line2": "177 River Valley Road",
    "city": "Singapore",
    "state": "Central",
    "country": "SG",
    "postal_code": "10015"
  },
  "line_items": null,
  "executor_id": 1363,
  "created_at": "2025-05-21T16:57:25",
  "updated_at": "2025-05-21T16:57:25",
  "staff_id": "98888a69-2d7a-4695-811d-6df8cee30264",
  "business_location_id": "9e42e6be-2ff8-4b37-ac14-07970d2e79ca",
  "metadata": {
    "key1": "value1",
    "key2": "value2"
  }
}

Headers

X-BUSINESS-API-KEY · string · required

Example:

"b286daabf9921b5a01a4621f026c111e046f8911feba212996c92159b98427d"

Body

application/json

currency · string · required

It's required field. Currency related to the payment.

Maximum string length: 3

Example:

"SGD"

amount · number<double>

It's optional field. Amount related to the payment. Example: 2500. If we pass, it should be greater than 0.3 and less than 999999999.99

Required range: 0.3 <= x <= 999999999.99

Example:

100

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

Example:

["card"]

email · string<email>

Buyer’s email

name · string

Buyer’s name

phone · string<phone>

Buyer’s phone number and should be in E.164 format. Example: [phone]

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

Example:

"98888a24-d6b2-430d-9063-d2be76d443cd"

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.

Example:

"9dd07721-d215-4947-9c79-2b8ec25f69db"

business_location_id · string<uuid>

The active location belongs to business.

Example:

"9dd07721-d215-4947-9c79-2b8ec25f69db"

purpose · string

Purpose of the Payment request.

Maximum string length: 255

reference_number · string

Arbitrary reference number that you can map to your internal reference number. This value cannot be edited by the customer

Maximum string length: 255

redirect_url · string<uri>

URL where we redirect the user after a payment. Query arguments reference (payment request id) and status are sent along

Maximum string length: 1028

Example:

"https://www.google.com"

webhook · string<uri>

URL where our server do POST request after a payment If done

Example:

"https://www.google.com"

allow_repeated_payments · enum<string> · default: false

If set to true, multiple payments can be paid on a payment request link. Default value is false

Available options: true, 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"

Example:

"5 minutes"

send_email · enum<string> · default: 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

Available options: true, false

send_sms · enum<string> · default: true

It's "true" or "false". If set to "true", SMS will be sent to the customer after the payment is completed. Default is false

Available options: true, false

address · object

Show child attributes

generate_qr · boolean · default: false

Only valid for paynow_online, qrph_netbank 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"}

Show child attributes

Response

200

application/json

200

id · string

Example:

"974ee233-bc3e-4aac-a212-15af0d155133"

name · string

Example:

"Buyer_Name_1663650582"

email · string

Example:

"[e-mail]"

phone · string

Example:

"[phone]"

amount · string

Example:

"900"

currency · string

Example:

"SGD"

status · enum<string>

Available options: pending, completed, failed, expired, canceled, inactive

Example:

"pending"

purpose · string

Example:

"Testing"

reference_number · string

Example:

"12345678"

payment_methods · string[]

Example:

"card"

url · string

Example:

"https://securecheckout.sandbox.hit-pay.com/payment-request/@ban/974ee233-bc3e-4aac-a212-15af0d155133/checkout"

redirect_url · string

Example:

"https://hit-pay.postman.co/"

webhook · string

Example:

"https://hit-pay.postman.co/"

send_sms · boolean

send_email · boolean · default: true

Example:

true

sms_status · string

Example:

"pending"

email_status · string

Example:

"pending"

allow_repeated_payments · boolean · default: false

Example:

false

expiry_date · string

Example:

"2022-10-10T01:01:01"

created_at · string

Example:

"2022-09-20T13:09:42"

updated_at · string

Example:

"2022-09-20T13:09:42"

staff_id · string | null

Example:

"98888a69-2d7a-4695-811d-6df8cee30264"

business_location_id · string | null

Example:

"9dd07721-d215-4947-9c79-2b8ec25f69db"

metadata · object

Show child attributes

Example:

{ "key1": "value1", "key2": "value2 " }