openapi: 3.1.1
info:
title: HitPay Account Status Payment Requests API
description: 'Accept PayNow, FPX, QRIS, GrabPay, cards, and 40+ payment methods with a single API. Production base URL: https://api.hit-pay.com, Sandbox: https://api.sandbox.hit-pay.com'
version: '1.0'
servers:
- url: https://api.hit-pay.com
description: Production
- url: https://api.sandbox.hit-pay.com
description: Sandbox
tags:
- name: Payment Requests
paths:
/v1/payment-requests:
post:
summary: Create Payment Request
description: '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.'
operationId: create-payment-request
parameters:
- name: X-BUSINESS-API-KEY
in: header
required: true
style: simple
explode: false
schema:
type: string
example: b286daabf9921b5a01a4621f026c111e046f8911feba212996c92159b98427d
requestBody:
content:
application/json:
schema:
type: object
required:
- amount
- currency
properties:
amount:
type: number
description: 'It''s required field. Amount related to the payment. Example: 2500'
format: double
example: 100
minimum: 0.3
maximum: 999999999.99
currency:
type: string
maxLength: 3
example: SGD
description: It's required field. Currency related to the payment.
payment_methods:
type: array
description: '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'
items:
type: string
example:
- card
email:
type: string
format: email
description: Buyer’s email
name:
type: string
description: Buyer’s name
phone:
type: string
format: phone
description: Buyer’s phone number
wifi_terminal_id:
type: string
description: It's terminal id and it's required if payment method is wifi_card_reader
staff_id:
type: string
format: uuid
description: It's active staff id from the dashboard
example: 98888a24-d6b2-430d-9063-d2be76d443cd
location_id:
type: string
format: uuid
example: 9dd07721-d215-4947-9c79-2b8ec25f69db
description: 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:
type: string
format: uuid
example: 9dd07721-d215-4947-9c79-2b8ec25f69db
description: The active location belongs to business.
purpose:
type: string
description: Purpose of the Payment request.
maxLength: 255
reference_number:
type: string
description: Arbitrary reference number that you can map to your internal reference number. This value cannot be edited by the customer
maxLength: 255
redirect_url:
type: string
format: uri
maxLength: 1028
example: https://www.google.com
description: URL where we redirect the user after a payment. Query arguments reference (payment request id) and status are sent along
webhook:
type: string
format: uri
example: https://www.google.com
description: URL where our server do POST request after a payment If done
allow_repeated_payments:
type: string
description: If set to true, multiple payments can be paid on a payment request link. Default value is false
default: 'false'
enum:
- 'true'
- 'false'
expiry_date:
type: string
description: 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:
type: string
description: E.g "30 mins" Other supported keys are "mins", "hours", "days"
example: 5 minutes
add_admin_fee:
type: string
description: If set to true, the admin fee will be included in total.
default: 'false'
enum:
- 'true'
- 'false'
send_email:
type: string
description: 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
default: 'false'
enum:
- 'true'
- 'false'
send_sms:
type: string
description: It's "true" or "false". If set to "true", SMS will be sent to the customer after the payment is completed. Default is false
default: 'true'
enum:
- 'true'
- 'false'
address:
type: object
required:
- line1
- city
- state
- country
- postal_code
properties:
line1:
type: string
line2:
type: string
city:
type: string
country:
type: string
state:
type: string
postal_code:
type: string
generate_qr:
type: boolean
default: false
description: Only valid for paynow_online, qrph_netbank, doku_qris and shopee_pay if generate_qr was true
metadata:
type: object
properties:
key:
type: string
description: '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"}'
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value:
id: 9ef68e2e-3569-4f69-9f68-04c7e4bb007c
name: Harvey Friesen
email: test@gmail.com
phone: '+65489505050'
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
schema:
type: object
properties:
id:
type: string
example: 974ee233-bc3e-4aac-a212-15af0d155133
name:
type: string
example: Buyer_Name_1663650582
email:
type: string
example: buyer_1663650582@gmail.com
phone:
type: string
examples:
- '+6539393939'
amount:
type: string
examples: '900'
currency:
type: string
example: SGD
status:
type: string
enum:
- pending
- completed
- failed
- expired
- canceled
- inactive
example: pending
purpose:
type: string
examples:
- Testing
reference_number:
type: string
example: '12345678'
payment_methods:
type: array
items:
type: string
examples:
- card
url:
type: string
example: https://securecheckout.sandbox.hit-pay.com/payment-request/@ban/974ee233-bc3e-4aac-a212-15af0d155133/checkout
redirect_url:
type: string
example: https://hit-pay.postman.co/
webhook:
type: string
example: https://hit-pay.postman.co/
send_sms:
type: boolean
send_email:
type: boolean
example: true
default: true
sms_status:
type: string
example: pending
email_status:
type: string
example: pending
allow_repeated_payments:
type: boolean
example: false
default: false
expiry_date:
type: string
example: '2022-10-10T01:01:01'
created_at:
type: string
example: '2022-09-20T13:09:42'
updated_at:
type: string
example: '2022-09-20T13:09:42'
staff_id:
type:
- string
- 'null'
example: 98888a69-2d7a-4695-811d-6df8cee30264
business_location_id:
type:
- string
- 'null'
example: 9dd07721-d215-4947-9c79-2b8ec25f69db
metadata:
type: object
properties:
key:
type: string
example:
key1: value1
key2: 'value2 '
'422':
description: '422'
content:
application/json:
examples:
Result:
value:
message: The currency field is required.
errors:
currency:
- The currency field is required.
schema:
oneOf:
- type: object
properties:
message:
type: string
examples:
- The given data was invalid.
errors:
type: object
properties:
amount:
type: array
items:
type: string
examples:
- The amount field is required.
currency:
type: array
items:
type: string
examples:
- The currency field is required.
- type: object
properties:
message:
type: string
examples:
- The given data was invalid.
errors:
type: object
properties:
amount:
type: array
items:
type: string
examples:
- The amount must be between 0.3 and 999999999.99.
- type: object
properties:
message:
type: string
examples:
- The given data was invalid.
errors:
type: object
properties:
payment_methods:
type: array
items:
type: string
examples:
- The selected payment methods is invalid.
deprecated: false
security: []
tags:
- Payment Requests
get:
summary: Get Payment Requests
description: Get all payment requests.
operationId: get-payment-requests
parameters:
- name: X-BUSINESS-API-KEY
in: header
required: true
style: simple
explode: false
schema:
type: string
example: b286daabf9921b5a01a4621f026c111e046f8911feba212996c92159b98427d
- name: per_page
in: query
description: Page size
schema:
type: integer
format: int32
default: 10
maximum: 100
- name: current_page
in: query
description: Page number (not `page`)
schema:
type: integer
format: int32
default: 1
- name: search
in: query
description: Partial match on email, id, or reference_number
schema:
type: string
maxLength: 255
- name: is_default
in: query
description: When set, returns only default payment links (channel = custom or link)
schema:
type: boolean
- name: metadata
in: query
description: Filter by metadata key/value (exact match); only the first key/value pair is used
schema:
oneOf:
- type: object
additionalProperties:
type: string
- type: array
items:
type: string
responses:
'200':
description: '200'
content: {}
deprecated: false
security: []
tags:
- Payment Requests
/v1/payment-requests/{request_id}:
put:
summary: Update Payment Request
description: This endpoint is to update the payment request.
operationId: update-payment-request
parameters:
- name: X-BUSINESS-API-KEY
in: header
required: true
style: simple
explode: false
schema:
type: string
example: b286daabf9921b5a01a4621f026c111e046f8911feba212996c92159b98427d
- name: request_id
in: path
description: It's payment request id
schema:
type: string
'format:': uuid
required: true
requestBody:
content:
application/json:
schema:
type: object
required:
- amount
- currency
properties:
amount:
type: number
description: It's required field. Amount related to the payment.
format: double
example: 100
minimum: 0.3
maximum: 999999999.99
currency:
type: string
maxLength: 3
example: SGD
description: Currency related to the payment.
payment_methods:
type: array
description: Payment method type (paynow_online , card, wechat, alipay, grabpay_direct, grabpay_paylater, shopee_pay, zip, fpx). If we don't pass, use the available methods
items:
type: string
email:
type: string
format: email
description: Buyer’s email
name:
type: string
description: Buyer’s name
phone:
type: string
format: phone
description: Buyer’s phone number
wifi_terminal_id:
type: string
description: It's terminal id and it's required if payment method is wifi_card_reader
staff_id:
type: string
format: uuid
example: 98888a24-d6b2-430d-9063-d2be76d443cd
description: It's active staff id from the dashboard
purpose:
type: string
description: Purpose of the Payment request.
maxLength: 255
reference_number:
type: string
description: Arbitrary reference number that you can map to your internal reference number. This value cannot be edited by the customer
maxLength: 255
redirect_url:
type: string
format: uri
maxLength: 1028
example: https://www.google.com
description: URL where we redirect the user after a payment. Query arguments reference (payment request id) and status are sent along
webhook:
type: string
format: uri
example: https://www.google.com
description: URL where our server do POST request after a payment If done
allow_repeated_payments:
type: string
description: If set to true, multiple payments can be paid on a payment request link. Default value is false
default: 'false'
enum:
- 'true'
- 'false'
expiry_date:
type: string
description: Time after which the payment link will be expired(time in SG with YYYY-MM-DD HH:mm:ss format). Applicable for repeated payments. Default is Null
expires_after:
type: string
description: E.g "30 mins" Other supported keys are "mins", "hours", "days"
example: 5 minutes
add_admin_fee:
type: string
description: If set to true, the admin fee will be included in total.
default: 'false'
enum:
- 'true'
- 'false'
send_email:
type: string
description: 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
default: 'false'
enum:
- 'true'
- 'false'
send_sms:
type: string
description: It's "true" or "false". If set to "true", SMS will be sent to the customer after the payment is completed. Default is false
default: 'true'
enum:
- 'true'
- 'false'
address:
type: object
required:
- line1
- city
- state
- country
- postal_code
properties:
line1:
type: string
line2:
type: string
city:
type: string
country:
type: string
state:
type: string
postal_code:
type: string
generate_qr:
type: boolean
default: false
description: 'Only valid for payment methods: paynow_online, qrph_netbank, doku_qris and shopee_pay if generate_qr was true'
responses:
'200':
description: '200'
content: {}
deprecated: false
security: []
tags:
- Payment Requests
delete:
summary: Delete Payment Request
description: 'This endpoint is to delete a specific payment request.
**Note: We don''t allow to delete the completed payment request.**'
operationId: delete-payment-request
parameters:
- name: X-BUSINESS-API-KEY
in: header
required: true
style: simple
explode: false
schema:
type: string
example: b286daabf9921b5a01a4621f026c111e046f8911feba212996c92159b98427d
- name: request_id
in: path
description: It's payment request id
schema:
type: string
'format:': uuid
required: true
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"success\": true\n}"
schema:
type: object
properties:
success:
type: boolean
examples:
- true
default: true
'404':
description: '404'
content:
application/json:
examples:
Result:
value: "{\n \"message\": \"No query results for model [App\\\\Business\\\\PaymentRequest] 974ee879-7feb-4bc6-b329-51f32928bd59\"\n}"
schema:
type: object
properties:
message:
type: string
examples:
- No query results for model [App\Business\PaymentRequest] 974ee879-7feb-4bc6-b329-51f32928bd59
deprecated: false
security: []
tags:
- Payment Requests
get:
summary: Get Payment Request Status
description: This endpoint is to get the status of a specific payment request.
operationId: get-payment-status
parameters:
- name: X-BUSINESS-API-KEY
in: header
required: true
style: simple
explode: false
schema:
type: string
example: b286daabf9921b5a01a4621f026c111e046f8911feba212996c92159b98427d
- name: request_id
in: path
description: It's required field
schema:
type: string
format: uuid
required: true
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value:
id: 9ef68e2e-3569-4f69-9f68-04c7e4bb007c
name: Harvey Friesen
email: test@gmail.com
phone: '+65489505050'
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:
city: Singapore
line1: 177 River Valley Road
line2: 177 River Valley Road
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
location:
id: 9e42e6be-2ff8-4b37-ac14-07970d2e79ca
name: API_Location_1740101762910
street: 58 Izpod Parkway
postal_code: 079903
city: Singapore
state: Singapore
country: sg
created_at: '2025-02-21T01:36:02.000000Z'
updated_at: '2025-02-21T01:36:02.000000Z'
active: true
business_id: 98567029-f559-49f9-916b-042a4255b32a
pickups: []
schema:
type: object
properties:
id:
type: string
name:
type: string
email:
type: string
phone:
type: string
amount:
type: string
currency:
type: string
status:
type: string
enum:
- pending
- completed
- failed
- expired
- canceled
- inactive
description: 'The status of the payment request. The value can be pending, completed, failed, expired, canceled or inactive.
`pending`: Default when a payment request is created: open for payment.
`failed`: Payment did not complete successfully.
`completed`: Payment succeeded, the request is treated as paid.(unless allow_repeated_payments applies).
`expired`: No longer payable because time ran out when either expiry_date or expires_after is set..
`canceled`: Manually or systematically voided (e.g. terminal flow canceling a pending request).
`inactive`: Payment link deactivated by the merchant.'
purpose:
type: string
reference_number:
type: string
payment_methods:
type: array
items:
type: string
url:
type: string
redirect_url:
type: string
webhook:
type: string
send_sms:
type: boolean
send_email:
type: boolean
sms_status:
type: string
email_status:
type: string
allow_repeated_payments:
type: boolean
expiry_date:
type: string
address:
type: object
properties:
city:
type: string
line1:
type: string
line2:
type: string
state:
type: string
country:
type: string
postal_code:
type: string
required:
- city
- line1
- line2
- state
- country
- postal_code
line_items:
type: array
items:
type: object
properties:
id:
type: string
sku:
type: string
url:
type: string
name:
type: string
price:
type: number
category:
type: string
quantity:
type: number
description:
type: string
required:
- id
- sku
- url
- name
- price
- category
- quantity
- description
created_at:
type: string
updated_at:
type: string
payments:
type: array
items:
type: object
properties:
id:
type: string
quantity:
type: number
status:
type: string
enum:
- pending
- requires_payment_method
- requires_customer_action
- succeeded_manually
- failed
- canceled
- void
- succeeded
- refunded
- partially_refu
# --- truncated at 32 KB (37 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hitpay/refs/heads/main/openapi/hitpay-payment-requests-api-openapi.yml