HitPay

https://docs.hitpayapp.com/
Admin
HitPay is a payment platform providing APIs, no-code tools, and integrations for businesses to...
Tokens:421,894
Snippets:3,483
Trust Score:9.8
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install and Login to HitPay CLI

Source: https://docs.hitpayapp.com/apis/guide/ai-developer-tools

Install the HitPay CLI globally and authenticate your session.

```bash
npm install -g @hit-pay/cli
hitpay login
```

--------------------------------

### Product Data Structure Example

Source: https://docs.hitpayapp.com/apis/product/create-product

Example of a product variation object including image dimensions and metadata.

```yaml
quantity_alert_level: 10
                        product_variation_weight: 255
                        variation_value_1: Large
                        variation_value_2: null
                        variation_value_3: null
                    variation_key_1: Size
                    variation_key_2: null
                    variation_key_3: null
                    images:
                      - id: 9a12fab6-1e76-448e-8c45-e84e2e38f294
                        caption: Beanie
                        url: <string>
                        other_dimensions:
                          - size: icon
                            path: <string>
                          - size: large
                            path: <string>
                          - size: small
                            path: <string>
                          - size: medium
                            path: <string>
                          - size: thumbnail
                            path: <string>
                    is_published: true
                    created_at: '2023-09-07T13:04:22+08:00'
                    updated_at: '2023-09-18T14:36:54+08:00'
                    starts_at: null
                    ends_at: null
```

--------------------------------

### Start Development Server

Source: https://docs.hitpayapp.com/development

Run this command in the directory containing mint.json to start the local documentation server at http://localhost:3000.

```bash
mintlify dev
```

--------------------------------

### OpenAPI Specification for Get Subscription Plan Details

Source: https://docs.hitpayapp.com/apis/recurring-billing/get-plan-details

The OpenAPI definition for the GET /v1/subscription-plan/{plan_id} endpoint, including request parameters and example responses for success and error scenarios.

```yaml
openapi: 3.1.1
info:
  title: HitPay 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
security: []
paths:
  /v1/subscription-plan/{plan_id}:
    get:
      summary: Get Subscription Plan Details
      description: >-
        Use this API to get the subscription plan details, if you need to make
        any changes use the Update a Subscription Plan API
      operationId: get-a-subscription-plan-detail
      parameters:
        - name: X-BUSINESS-API-KEY
          in: header
          required: true
          style: simple
          explode: false
          schema:
            type: string
            example: b286daabf9921b5a01a4621f026c111e046f8911feba212996c92159b98427d
        - name: plan_id
          in: path
          schema:
            type: string
          required: true
      responses:
        '200':
          description: '200'
          content:
            application/json:
              examples:
                Result:
                  value: |-
                    {
                        "id": "973ee344-6737-4897-9929-edbc9d7bf433",
                        "name": "Spotify Premium",
                        "description": "Spotify Monthly Subscription",
                        "cycle": "monthly",
                        "cycle_repeat": null,
                        "cycle_frequency": null,
                        "currency": "sgd",
                        "amount": 9.9,
                        "reference": "spotify_premium_2022",
                        "created_at": "2022-09-12T14:22:26",
                        "updated_at": "2022-09-12T14:22:26"
                    }
              schema:
                type: object
                properties:
                  id:
                    type: string
                    examples:
                      - 973ee344-6737-4897-9929-edbc9d7bf433
                  name:
                    type: string
                    examples:
                      - Spotify Premium
                  description:
                    type: string
                    examples:
                      - Spotify Monthly Subscription
                  cycle:
                    type: string
                    examples:
                      - monthly
                  cycle_repeat: {}
                  cycle_frequency: {}
                  currency:
                    type: string
                    examples:
                      - sgd
                  amount:
                    type: number
                    examples:
                      - 9.9
                    default: 0
                  reference:
                    type: string
                    examples:
                      - spotify_premium_2022
                  created_at:
                    type: string
                    examples:
                      - '2022-09-12T14:22:26'
                  updated_at:
                    type: string
                    examples:
                      - '2022-09-12T14:22:26'
        '422':
          description: '422'
          content:
            application/json:
              examples:
                Result:
                  value: |-
                    {
                        "message": "No query results for model [App\\Business\\SubscriptionPlan] 973ee456-d28f-4418-93c5-d37e4b311685"
                    }
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - >-
                        No query results for model
                        [App\Business\SubscriptionPlan]
                        973ee456-d28f-4418-93c5-d37e4b311685
      deprecated: false
      security: []
```

--------------------------------

### Address Already in Use Error

Source: https://docs.hitpayapp.com/development

Example of the error message displayed when attempting to start Mintlify on a port that is already occupied.

```md
Error: listen EADDRINUSE: address already in use :::3000
```

--------------------------------

### Install HitPay CLI from Source

Source: https://docs.hitpayapp.com/apis/guide/cli

Use this method if the npm package is unavailable or fails during the beta phase.

```bash
git clone https://github.com/hit-pay/cli.git
cd cli && npm install && npm run build && npm link
```

--------------------------------

### GET /v1/account-status

Source: https://docs.hitpayapp.com/apis/accounts/account-status

Retrieves the current status of the HitPay account, including verification details and the setup status of payment providers.

```APIDOC
## GET /v1/account-status

### Description
Get the account status including verification and payment provider setup.

### Method
GET

### Endpoint
/v1/account-status

### Parameters
#### Header Parameters
- **X-BUSINESS-API-KEY** (string) - Required - Your HitPay API key.

### Response
#### Success Response (200)
- **bank_account_status** (string) - Status of the bank account.
- **verification** (object) - Verification details including overall_status, owner_verification, and business_verification.
- **payment_providers** (object) - Map of payment providers and their setup status.

#### Response Example
{
  "bank_account_status": "completed",
  "verification": {
    "overall_status": "completed",
    "owner_verification": "not_required",
    "business_verification": "completed"
  },
  "payment_providers": {
    "airwallex_sg": { "setup_status": "completed" },
    "stripe_sg": { "setup_status": "completed", "payment_enabled": true, "payout_enabled": true }
  }
}
```

--------------------------------

### Create Subscription Plan with PHP

Source: https://docs.hitpayapp.com/apis/guide/recurring-billing

Example of creating a subscription plan using the Guzzle HTTP client in PHP.

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.staging.hit-pay.com/v1/subscription-plan', [
  'form_params' =>[
  	'name' => 'Spotify Premium',
    'description' => 'Spotify Monthly Subscription',
  	'currency' => 'SGD'
  	'amount' => 9.90,
  	'cycle' => 'monthly',
  	'reference' => 'spotify_premium_2022'
  ],
  'headers' => [
    'Content-Type' => 'application/x-www-form-urlencoded',
    'X-Requested-With' => 'XMLHttpRequest',
    'accept' => 'application/json',
    'x-api-key' => 'meowmeowmeow',
  ],
]);

echo $response->getBody();
```

--------------------------------

### OpenAPI Definition for GET /v1/staffs

Source: https://docs.hitpayapp.com/apis/staffs/staffs

This YAML snippet defines the HitPay API endpoint for retrieving all staff members. It includes the required X-BUSINESS-API-KEY header and an example response structure.

```yaml
openapi: 3.1.1
info:
  title: HitPay 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
security: []
paths:
  /v1/staffs:
    get:
      summary: Get All Staffs
      description: Get All Staffs
      operationId: get-all-staffs
      parameters:
        - name: X-BUSINESS-API-KEY
          in: header
          required: true
          style: simple
          explode: false
          schema:
            type: string
            example: b286daabf9921b5a01a4621f026c111e046f8911feba212996c92159b98427d
      responses:
        '200':
          description: '200'
          content:
            application/json:
              examples:
                Result:
                  value:
                    - id: 98566f58-1c76-4b8b-8f75-d20bba2bc7f8
                      name: TestingSG
                      role:
                        id: 93a00e56-c832-490e-b5b8-7f08149548c7
                        title: Owner
                    - id: 98888a24-d6b2-430d-9063-d2be76d443cd
                      name: SG11
                      role:
                        id: 93a00e56-d9d8-46f7-aa41-da868820f899
                        title: Manager
                    - id: 98888a69-2d7a-4695-811d-6df8cee30264
                      name: SG
                      role:
                        id: 93a00e56-d9d8-46f7-aa41-da868820f899
                        title: Manager
                    - id: 98888a7a-8d02-48bd-ba00-9ea91ad30ecb
                      name: Cashier 01
                      role:
                        id: 93a00e56-dbea-4387-8972-e04777d9afce
                        title: Cashier
                    - id: 98889105-0aa7-4480-989c-41f38172b4e6
                      name: Cashier 02
                      role:
                        id: 93a00e56-dbea-4387-8972-e04777d9afce
                        title: Cashier
                    - id: 9888918e-246b-44c6-a602-d8bcfd726345
                      name: Admin 01
                      role:
                        id: 93a00e56-d68c-4025-9cea-2b08cd50572e
                        title: Admin
                    - id: 9bf2c210-9516-4525-9a8f-52cb671e7b02
                      name: Manager 01
                      role:
                        id: 93a00e56-d9d8-46f7-aa41-da868820f899
                        title: Manager
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    name:
                      type: string
                    role:
                      type: object
                      properties:
                        id:
                          type: string
                        title:
                          type: string
                      required:
                        - id
                        - title
                  required:
                    - id
                    - name
                    - role
      deprecated: false
```

--------------------------------

### Client: Collect customer info and initiate setup

Source: https://docs.hitpayapp.com/connections/stripe/auto-charge

Collect customer details and perform sequential server calls to create a Stripe subscription and a HitPay authorization session.

```typescript
// 1. Create Stripe subscription — returns subscription + invoice details
const subRes = await fetch('/api/create-subscription', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email,
    priceId,           // Stripe Price ID for the selected plan
    cpmTypeId,         // Stripe CPM Type ID for the selected payment method
  }),
});
const { subscriptionId, customerId, invoiceId, invoiceAmount, currency } = await subRes.json();

// 2. Create HitPay recurring billing session — returns authorization embed data
const hitpayRes = await fetch('/api/hitpay/recurring-billing/create', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    customerId,
    subscriptionId,
    invoiceId,
    amount: invoiceAmount,
    currency,
    customerEmail: email,
    paymentMethod: selectedRecurringMethod, // e.g. 'card', 'shopee_recurring', 'grabpay_direct'
  }),
});
const { directLinkUrl, directLinkAppUrl, qrCode } = await hitpayRes.json();

// → Pass this data to Step 3 to render inline authorization
```

--------------------------------

### Beneficiary Response Example

Source: https://docs.hitpayapp.com/apis/payout/create-beneficiary

An example of a successful beneficiary object response.

```json
transfer_type: local
nickname: null
remark: null
holder_name: John Test
holder_type: individual
account_number: '1409828'
bank_name: BANK OF AMERICA
bank_id: BOFASG2XXXX[7065]
email: null
bank_swift_code: BOFASG2XXXX
is_favourite: false
created_by:
  id: 98566f58-1c76-4b8b-8f75-d20bba2bc7f8
  display_name: TestingSG
  first_name: QA
  last_name: SG
created_at: '2025-04-24T15:13:22+08:00'
updated_at: '2025-04-24T15:13:22+08:00'
deleted_at: null
```

--------------------------------

### Metadata Example

Source: https://docs.hitpayapp.com/apis/payment-request/create-request

Example of the metadata object structure for key-value pairs.

```json
{"car_model": "toyota", "car_color": "red"}
```

--------------------------------

### Initiate Card Payment in PHP

Source: https://docs.hitpayapp.com/apis/guide/in-person-payments/overview

Example of initiating a card payment request using the PHP http client. Requires setting the payment_methods parameter to wifi_card_reader and providing the wifi_terminal_id.

```php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api.sandbox.hit-pay.com/v1/payment-requests');
$request->setRequestMethod('POST');
$body = new http\Message\Body;
$body->append(new http\QueryString(array(
  'amount' => '599',
  'currency' => 'SGD',
  'payment_methods[]' => 'wifi_card_reader',
  'wifi_terminal_id' => 'tmr_123123123')));
$request->setBody($body);
$request->setOptions(array());
$request->setHeaders(array(
  'X-BUSINESS-API-KEY' => 'meowmeowmeow',
  'Content-Type' => 'application/x-www-form-urlencoded',
  'X-Requested-With' => 'XMLHttpRequest'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
```

--------------------------------

### Install Mintlify CLI

Source: https://docs.hitpayapp.com/development

Install the Mintlify CLI globally using either npm or yarn. Requires Node.js version 18.10.0 or higher.

```bash
npm i -g mintlify
```

```bash
yarn global add mintlify
```

--------------------------------

### GET /v1/subscription-plan

Source: https://docs.hitpayapp.com/apis/recurring-billing/get-all-plans

Use this API to get all subscription plans details.

```APIDOC
## GET /v1/subscription-plan

### Description
Use this API to get all subscription plans details.

### Method
GET

### Endpoint
/v1/subscription-plan

### Parameters
#### Header Parameters
- **X-BUSINESS-API-KEY** (string) - Required - The business API key for authentication.

#### Query Parameters
- **per_page** (number) - Optional - The number of items per page (default: 20).
- **page** (number) - Optional - The page index (default: 1).

### Response
#### Success Response (200)
- **data** (array) - List of subscription plan objects.
- **links** (object) - Pagination links.
- **meta** (object) - Pagination metadata.

#### Response Example
{
    "data": [
        {
            "id": "975b1909-38f6-44f3-a0b1-c198b7478978",
            "name": "subscription-plan_new_1664175178",
            "description": "New_Description_1664175178",
            "cycle": "custom",
            "cycle_repeat": 1,
            "cycle_frequency": "day",
            "currency": "sgd",
            "price": 123.45,
            "amount": 123.45,
            "reference": null,
            "created_at": "2022-09-26T14:52:58",
            "updated_at": "2022-09-26T14:52:58"
        }
    ],
    "links": {
        "first": "https://api.sandbox.hit-pay.com/v1/subscription-plan?page=1",
        "last": "https://api.sandbox.hit-pay.com/v1/subscription-plan?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "https://api.sandbox.hit-pay.com/v1/subscription-plan",
        "per_page": 25,
        "to": 2,
        "total": 2
    }
}
```

--------------------------------

### PublicUpdateLocationActive API Key Example

Source: https://docs.hitpayapp.com/apis/locations/toggle-location-active

Example of the X-BUSINESS-API-KEY header required for authentication.

```text
b286daabf9921b5a01a4621f026c111e046f8911feba212996c92159b98427d
```

--------------------------------

### Product Creation Response Example

Source: https://docs.hitpayapp.com/apis/product/create-product

The successful response returned after creating a product, containing the product ID, business ID, and variation details.

```json
{
  "id": "9a12fab4-d112-48af-9d6b-050d650b0a25",
  "business_id": "9130c422-bf97-4bd1-b370-07a3a6f40708",
  "category_id": [
    "9a12fab0-d282-4437-9460-c3d26662d11a"
  ],
  "name": "Beanie",
  "headline": null,
  "description": "<p>Stylish hat suitable for the winter.</p>",
  "currency": "SGD",
  "price": 15,
  "price_display": "SGD 15.00",
  "price_stored": 1500,
  "tax_id": null,
  "is_manageable": 1,
  "is_pinned": false,
  "status": "published",
  "product_weight": 250,
  "delivery_method_required": true,
  "has_variations": true,
  "is_shopify": false,
  "product_url": "<string>",
  "variations_count": 2,
  "variations": [
    {
      "id": "9a12fab4-d998-44ea-ad11-8753be88a1c9",
      "stock_keeping_unit": null,
      "description": "Medium",
      "weight": null,
      "length": null,
      "width": null,
      "depth": null,
      "price": 18,
      "price_display": "SGD 18.00",
      "price_stored": 1800,
      "quantity": 150,
      "quantity_alert_level": 10,
      "product_variation_weight": 250,
      "variation_value_1": "Medium",
      "variation_value_2": null,
      "variation_value_3": null
    },
    {
      "id": "9a12fab4-dd20-4f8f-9e74-de28629f863a",
      "stock_keeping_unit": null,
      "description": "Large",
      "weight": null,
      "length": null,
      "width": null,
      "depth": null,
      "price": 20,
      "price_display": "SGD 20.00",
      "price_stored": 2000,
      "quantity": 148
    }
  ]
}
```
Tokens:
Raw