Wisenet Finance is being updated.
This article provides you with information related changes that we’re making to some Finance API models and endpoints.
These changes support a more flexible approach to Wisenet Finance, particularly around how payments, invoices, allocations and refunds are managed.
If your organisation has an integration that consumes Wisenet Finance APIs, we recommend reviewing the changes below and updating your integration where required.
What’s changing?
The most significant change being made in this update is the relationship between payments and invoices.
Previously, a payment could be linked directly to a single invoice. Wisenet Finance is moving to an allocation-based model, allowing payments and other financial transactions to be allocated across invoices.
As a result, several existing Finance API fields and relationships are changing.
Payment and invoice relationships
Affected endpoints:
- GET /finance-payments
- GET /finance-payments/{id}
The existing direct payment-to-invoice relationship is being replaced with an allocation model.
The following changes will apply to FinancePayment:
- FinanceInvoiceId will be removed.
- relationships.Invoice will be replaced by relationships.FinanceInvoices[].
- Each invoice relationship will include an AllocatedAmount, representing the amount of the payment allocated to that invoice.
- relationships.FinanceRefund will be replaced by relationships.FinanceRefunds[].
- FinanceInvoiceStatuses will be added.
- UnutilisedAmount will be added.
Existing payments linked to an invoice will be migrated to the new allocation model as part of the release.
What to do if this impacts you
Update integrations that currently read FinanceInvoiceId or relationships.Invoice from a payment.
Use relationships.FinanceInvoices[] and the associated AllocatedAmount to determine which invoices a payment has been allocated to and the amount allocated to each.
Integrations using relationships.FinanceRefund should also be updated to consume the new relationships.FinanceRefunds[] array.
Payment statuses are changing
Affected endpoint:
- GET /finance-payments
The FinancePaymentStatus lookup is being restructured.
Following the release:
- Status ID 1 will change from Received to Posted.
- Status ID 2, previously Refunded, will become Draft.
- Refunds will no longer be represented through the payment status. They will instead be represented by Finance Refund records.
- Existing payments that are not already status ID 1 will be migrated to Posted as part of the release.
- New payments can be created with a Draft status.
What to do if this impacts you
Review any integration logic, filtering or display behaviour that relies on Finance Payment status IDs or names.
In particular, do not continue to interpret status ID 2 as Refunded after this release.
Unutilised Amount added to payments
Affected endpoint:
- GET /finance-payments
FinancePayment will include a new UnutilisedAmount decimal field.
This represents:
PaymentAmount – Allocations – Refunds
It provides the remaining amount of a payment that has not been allocated or refunded.
What to do if this impacts you
No change is required if your integration does not need this information.
If your integration currently calculates the remaining balance of a payment itself, we recommend using UnutilisedAmount returned by the API instead.
Invoice allocations replace Finance Credits
Affected endpoints:
- GET /finance-invoices/{id}
- GET /finance-invoices/guid/{guid}
The FinanceInvoiceAggregate response is changing to align with the new allocation model.
FinanceCredits[] will be removed from the response.
The following will instead be available within relationships:
- FinanceAllocations[]
- FinancePaymentStatuses[]
FinanceAllocations[] should be used to determine the payments and credit notes allocated to an invoice, including the amount allocated.
What to do if this impacts you
Stop consuming FinanceCredits, as this field will no longer be returned.
Update integrations to use relationships.FinanceAllocations[] when determining the financial transactions applied to an invoice.
LastPaymentDate removed from invoice responses
Affected endpoints:
- GET /finance-invoices/{id}
- GET /finance-invoices/guid/{guid}
LastPaymentDate will be removed from FinanceInvoiceAggregate.
What to do if this impacts you
If your integration currently consumes LastPaymentDate, use the allocation information available through relationships.FinanceAllocations[] to determine relevant allocation dates.
CurrencyId will no longer be nullable
CurrencyId is changing from a nullable value to a non-nullable integer in the following response models:
- FinanceInvoiceAggregate
- FinanceInvoiceBasic
These models are returned across Finance Invoice, Finance Payment and Quote endpoints.
Existing records where CurrencyId was null will be updated using the organisation’s default currency as part of the migration.
What to do if this impacts you
Integrations no longer need to account for a null CurrencyId. Following the release, the field will always contain a positive integer.
Finance date fields
Date fields across Finance API request and response models will continue to be represented as full ISO 8601 datetime values.
For date-only Finance fields, the time component will always be Calendar Date.
For example:
2024-03-01T00:00:00
This applies to Finance fields including:
- IssueDate
- RefundDate
- WriteOffDate
- PaymentDate
- AllocationDate
What to do if this impacts you
Ensure integrations can parse these values as full ISO 8601 datetime values.
The time component should not be interpreted as meaningful for these fields.
What do developers need to do?
If your integration uses Wisenet Finance APIs, review your implementation for dependencies on:
- FinanceInvoiceId on payments
- relationships.Invoice
- relationships.FinanceRefund
- FinanceCredits
- LastPaymentDate
- Existing Finance Payment status IDs or names
- Nullable CurrencyId handling
- Finance date parsing
The move to allocations is particularly important. Integrations should no longer assume that a payment has a one-to-one relationship with an invoice.
Instead, integrations should be designed around the allocation model, where a payment can have allocations across invoice relationships and its remaining balance is represented by UnutilisedAmount.
The updated end points will only become available on release day. While you can review and prepare for the changes in advance, testing will not be possible before the release.