The Financial API - Invoices & Receivables allows you to manage invoices, payments, and receivables within the Equus Platform, ensuring seamless synchronization with external accounting systems. This API facilitates structured financial workflows by enabling invoice tracking, payment applications, and receivables reconciliation.
The API ensures that Equus remains the system of record for financial transactions related to mobility services, while integration with external financial systems requires middleware or user-managed financial platforms to handle data tracking, mapping, and transformations.
This integration supports a two-way data exchange, allowing:
Outbound data transfer: Equus sends invoice and receivable data via scheduled web requests.
Inbound updates: Clients can PATCH invoice statuses and payment details back into Equus to confirm updates in external financial systems.
Supported Operations
The API supports GET, POST, and PATCH methods for managing invoices and receivables.
API Endpoints
Method | Endpoint | Description |
GET | /invoices/{id} | Retrieve invoice details |
POST | /payments | Create a paymentCredit record |
POST | /payments/apply | Apply a payment to an invoice |
PATCH | /payments/apply/{id} | Update applied payment amount |
Data Model
Invoices
Field | Type | Description |
invoiceId | Integer | Unique identifier for the voucher |
amountDue | Decimal | Outstanding invoice balance |
postDate | Date | Date the invoice was recorded in the system |
status | String | Invoice status (e.g., pending, posted, paid) |
Payment
Field | Type | Description |
paymentCreditId | Integer | Unique identifier for the payment record |
amount | Decimal | Payment amount |
currency | String | Currency of the payment |
receivedFrom | String | Source of the payment |
Integration with User Report Scheduler
The User Report Scheduler can be leveraged to automate the export of invoices and receivables data from Equus to an external financial system via scheduled web requests.
When configuring invoice exports using the User Report Scheduler, clients can:
Schedule reports at custom intervals (hourly, daily, etc.).
Configure JSON payload formats that match external system expectations.
Define a target URL for automated report deliveries.
For detailed instructions on how to configure scheduled reports for financial data, refer to the User Report Scheduler documentation.
Invoices & Receivables Workflow
Invoice Status Updated Upon Receipt in Accounting System - Once invoice data has been exported from the Equus Platform, the invoice status will be updated via a PATCH request to confirm receipt in the accounting system. The invoice ID will be stored in the accounting system for future updates.
Invoice Payment Recorded - When the invoice is paid, the 'paymentCredit' details will be updated in Equus using a POST request. If both invoice ID and 'paymentCredit' ID are stored, they will be updated directly. Otherwise, GET requests will be used to retrieve the necessary IDs before updating.
Invoice Status Finalized & Payment Applied - Once the invoice is partially or fully paid, a final PATCH request will be sent to update the invoice status. A 'paymentCreditApply' record will be created to track payments against the invoice. If exchange rates caused a payment amount change, the 'totalAmount' and 'appliedAmount' fields will be updated.
Logging & Error Handling
For tracking the status of outbound requests and updates, the system logs the following:
Field | Type | Description |
WEBHOOK_PROFILE_ID
| Integer | Reference to webhook profile |
TARGET_URL | String | Destination URL for web request |
REQUEST_BODY | String | JSON payload sent |
HTTP_METHOD | String | HTTP verb used (POST, PATCH) |
MAX_RETRIES | Integer | Maximum retry attempts |
RETRY_COUNT | Integer | Number of retries performed |
LAST_RESPONSE_STATUS_CODE | Integer | Last HTTP status received |
LAST_RETRY_FAILURE_MESSAGE | String | Error details if last attempt failed |
Things to Note
The 'invoiceStatusId' is treated as a lookup attribute, allowing API users to retrieve or update status values using both ID and display values. The API does not support deleting invoices, and updates must be made via PATCH requests.
The business financial platform or middleware is responsible for tracking and mapping invoice IDs, payment records, tax codes, and customer data. Cross-system record mapping, such as charge categories, charge codes, and vendors, must be handled externally. Any currency conversions required for processing payments must be managed by the financial platform.
The API only allows PATCH updates for specific fields, ensuring that existing financial data remains accurate and unchanged. Payments should always be applied based on pre-configured financial rules to maintain accuracy.
Security & Access Control
Access to the Financial API requires an API Subscription and Permission Set, ensuring that only authorized users can retrieve and update financial data. The feature still observes access and user roles as part of its configuration and security measures.
For further details or integration support, please contact your Equus representative.