Key Concepts

Learn the essential components for integrating with the HarpFi APIs, including authentication, environment setup, onboarding, balances, and webhooks.

Service URLs

Every request uses one of the two following URLs, depending on whether you're working in your live environment (production) or your test environment (sandbox).

Request ID

Every API response includes a unique request ID in the response headers. This request ID is essential for debugging purposes and should be included when contacting support about specific API requests.

The request ID is returned in the x-request-id header of all API responses. When you encounter an issue or need assistance, providing this request ID helps our support team quickly locate and investigate the specific request in our systems.

Example Response Header:

x-request-id: req-1234567890abcdef

Note: Always capture and store the request ID from response headers when making API calls. This will significantly speed up troubleshooting if you need to contact support.

Pagination

HarpFi API uses cursor-based pagination for efficient data retrieval. This approach provides consistent results even when data changes between requests.

Pagination Structure

All paginated endpoints return data in this format:

{
    "success": true,
    "message": "Payments retrieved successfully",
    "data": {
        "records": [...],
        "paging": {
            "totalCount": 10,
            "nextPage": "string",
            "previousPage": "string"
        }
    }
}

How It Works

• records: Array of items for the current page
• totalCount: Total number of items available across all pages
• nextPage: Cursor token to fetch the next page (use as page parameter)
• previousPage: Cursor token to fetch the previous page (use as page parameter)

Making Requests

To navigate pages, include the cursor token and limit in your request:

• Next page: GET /endpoint?page=nextPage&limit=50
• Previous page: GET /endpoint?page=previousPage&limit=50
• First page: GET /endpoint?limit=50 (no page parameter)

Parameters

• page: Cursor token for pagination (optional)
• limit: Number of items per page (optional, min: 1, max: 100)

Errors

{
    "success": false,
    "code": "invalid_request",
    "message": "Invalid request data",
    "data": [
        {
            "code": "required",
            "fieldName": "address",
            "message": "This field is required"
        }
    ]
}