Sign in

v2

latestOpenAPI 3.1.12026-08-06856719.6 KB

Create Payment Request

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.

post/v1/payment-requests

Headers

X-BUSINESS-API-KEYstring required
Example:b286daabf9921b5a01a4621f026c111e046f8911feba212996c92159b98427d

Request body

amountnumber double required

It's required field. Amount related to the payment. Example: 2500

currencystring required

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

payment_methodsstring[]

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

emailstring email

Buyer’s email

namestring

Buyer’s name

phonestring phone

Buyer’s phone number

wifi_terminal_idstring

It's terminal id and it's required if payment method is wifi_card_reader

staff_idstring uuid

It's active staff id from the dashboard

location_idstring 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_idstring uuid

The active location belongs to business.

purposestring

Purpose of the Payment request.

reference_numberstring

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

redirect_urlstring uri

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

webhookstring 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_datestring

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_afterstring

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

generate_qrboolean

Only valid for paynow_online, qrph_netbank, doku_qris and shopee_pay if generate_qr was true

Example request

{
  "amount": 100,
  "currency": "SGD",
  "payment_methods": [
    "card"
  ],
  "staff_id": "98888a24-d6b2-430d-9063-d2be76d443cd",
  "location_id": "9dd07721-d215-4947-9c79-2b8ec25f69db",
  "business_location_id": "9dd07721-d215-4947-9c79-2b8ec25f69db",
  "redirect_url": "https://www.google.com",
  "webhook": "https://www.google.com",
  "expires_after": "5 minutes"
}

Response

200

idstring
namestring
emailstring
phonestring
amountstring
currencystring
status'pending' | 'completed' | 'failed' | 'expired' | 'canceled' | 'inactive'
purposestring
reference_numberstring
payment_methodsstring[]
urlstring
redirect_urlstring
webhookstring
send_smsboolean
send_emailboolean
sms_statusstring
email_statusstring
allow_repeated_paymentsboolean
expiry_datestring
created_atstring
updated_atstring
staff_idstring nullable
business_location_idstring nullable

Example response

{
  "id": "974ee233-bc3e-4aac-a212-15af0d155133",
  "name": "Buyer_Name_1663650582",
  "email": "buyer_1663650582@gmail.com",
  "phone": "+6539393939",
  "currency": "SGD",
  "status": "pending",
  "purpose": "Testing",
  "reference_number": "12345678",
  "url": "https://securecheckout.sandbox.hit-pay.com/payment-request/@ban/974ee233-bc3e-4aac-a212-15af0d155133/checkout",
  "redirect_url": "https://hit-pay.postman.co/",
  "webhook": "https://hit-pay.postman.co/",
  "send_email": true,
  "sms_status": "pending",
  "email_status": "pending",
  "expiry_date": "2022-10-10T01:01:01",
  "created_at": "2022-09-20T13:09:42",
  "updated_at": "2022-09-20T13:09:42",
  "staff_id": "98888a69-2d7a-4695-811d-6df8cee30264",
  "business_location_id": "9dd07721-d215-4947-9c79-2b8ec25f69db",
  "metadata": {
    "key1": "value1",
    "key2": "value2 "
  }
}