PayConnect
Provides integration with PayConnect for template-driven invoice creation, retrieval, updates, payments, email, and void operations.
Revision History
0.1.0.1 - Preserved inherited fields in designer templates when OpenAPI schemas use constraints-only allOf overlays.
0.1.0.0 - Completed the V2 overhaul with eager first-request startup and lazy continuation.
0.0.0.4 - Aligned the V2 connector contract and public help article.
0.0.0.1 - Initial PayConnect Node article for the invoice-first V2 connector surface.
0.0.0.2 - Expanded the direct invoice surface to include get-by-id and pay-invoice operations.
0.0.0.3 - Updated get-by-id behavior to return invoices through the working invoice search path when the direct provider route returns unauthorized.
0.0.0.4 - Updated the Node for net8.0 and net10.0 deployments.
0.0.0.8 - Normalized known epoch date and date-time fields in provider responses.
Connection
The PayConnect Connection stores the values the Node uses to authenticate invoice requests.
| Property | Type | Description |
|---|---|---|
Use Production Environment |
Boolean | Uses the production PayConnect API endpoints instead of the sandbox endpoints. |
API Key |
Masked | The PayConnect API key used to create a session token. The Node formats the required Api-Key authorization header for you. |
Session Token |
Masked | The cached PayConnect session token used for invoice requests. This value is managed by the Node at runtime. |
Session Expires At (UTC) |
String | The UTC expiry value returned for the current session token. This value is managed by the Node at runtime. |
Timeout (seconds) |
Integer | The HTTP timeout, in seconds, used for session creation and validation calls. |
Setup Notes
Create a PayConnect Connection before using the Node in a Workflow.
The Node supports both sandbox and production environments:
- Sandbox:
https://dev.payconnect.us/api - Production:
https://my.payconnect.us/api
The Node creates and refreshes short-lived PayConnect session tokens automatically from the API key stored in the Connection.
Connection testing uses invoice search to confirm that the API key can create a session token and that the session token can access the supported invoice surface.
Runtime requests retry once after a stale-session 401 so the Node can refresh the session token and continue without requiring a manual reconnect.
Deploy the package that matches your runtime. The current PayConnect Node supports both net8.0 and net10.0.
Methods
The PayConnect Node exposes four methods. The available templates under these methods cover the supported direct PayConnect invoice operations:
- Create invoice
- Search invoices
- Get invoice by ID
- Update invoice
- Pay invoice
- Send invoice email
- Void invoice
Create
Use Create to create invoices.
| Parameter | Type | Description |
|---|---|---|
Connection |
Connection | The PayConnect Connection to use for the request. |
OperationId |
String | Identifies the create template to execute. |
Options |
Object | Additional route values required by the selected create template. |
Items |
Array | The structured request body for the selected create template. |
| Return | Type | Description |
|---|---|---|
Response |
Array | Returns provider payload fields together with the Flowgear Flowgear.IsSuccess and Flowgear.Message mutation defaults. |
Retrieve
Use Retrieve to search invoices or get one invoice by ID.
| Parameter | Type | Description |
|---|---|---|
Connection |
Connection | The PayConnect Connection to use for the request. |
OperationId |
String | Identifies the retrieve template to execute. |
Options |
Object | The structured options for the selected retrieve template. Search templates accept structured search filters and the Node handles paging internally. Get-by-ID requires invoiceId. |
| Return | Type | Description |
|---|---|---|
Response |
Array | Search returns one business row per invoice and includes a pagination object on each row. Get-by-ID returns the matching invoice row when found. Retrieve rows do not include mutation-style default fields. |
Update
Use Update to update invoices.
| Parameter | Type | Description |
|---|---|---|
Connection |
Connection | The PayConnect Connection to use for the request. |
OperationId |
String | Identifies the update template to execute. |
Options |
Object | Additional route values required by the selected update template. |
Items |
Array | The structured request body for the selected update template. |
| Return | Type | Description |
|---|---|---|
Response |
Array | Returns provider payload fields together with the Flowgear Flowgear.IsSuccess and Flowgear.Message mutation defaults. |
Action
Use Action to run invoice actions such as pay-invoice, send-email, and void.
| Parameter | Type | Description |
|---|---|---|
Connection |
Connection | The PayConnect Connection to use for the request. |
OperationId |
String | Identifies the action template to execute. |
Options |
Object | Additional route values required by the selected action template. |
Items |
Array | The structured request body for the selected action template when the action requires one. |
| Return | Type | Description |
|---|---|---|
Response |
Array | Returns provider payload fields together with the Flowgear Flowgear.IsSuccess and Flowgear.Message mutation defaults. |
Usage Notes
Use the method templates to select the supported PayConnect operation instead of entering raw endpoint details manually.
Retrieve completes the first PayConnect provider request while the Node invoke is awaited. Any later search pages are fetched only as the Workflow consumes the response stream.
Create, Update, and Action complete the first input item while the Node invoke is awaited. Later items are consumed lazily, and an empty connected input sends no provider request.
For invoice search, the Node emits one row per invoice instead of a single wrapper row. The PayConnect pagination metadata is attached to each emitted invoice row.
If an invoice search returns no invoices, the Node still emits one success row so the pagination metadata remains available to the Workflow.
Get-by-ID tries the direct PayConnect invoice route first and falls back to invoice search only when that direct route returns the known unauthorized failure shape for an otherwise valid session.
Retrieve rows stay focused on PayConnect business data and do not include mutation-style default fields.
If the first provider retrieve call fails, the Node surfaces that PayConnect error instead of converting it into an empty result.
Create, Update, and Action rows use the Flowgear mutation defaults through the Flowgear object. When a PayConnect mutation response includes a provider status field that would otherwise collide with the Flowgear contract, the provider value is returned as providerStatus.
When you emit multiple Items rows for Create, Update, or Action, the Node sends one PayConnect request per emitted row instead of batching them into one JSON array body.
Known date-like response fields containing epoch seconds or milliseconds are normalized recursively. Date fields use yyyy-MM-dd, and date-time fields use an ISO round-trip timestamp. Numeric fields that are not recognized as dates remain unchanged.
Known Issues
- The Node still targets the direct invoice API surface only. Hosted-payment helpers, company-scoped management APIs, subscriptions, customers, and transaction-management endpoints remain outside the current V2 Node surface.
- PayConnect does not publicly document the complete search filter vocabulary, so available search filtering is limited to the documented template surface.