Invoices serve as records of the outstanding balances owed by customers and can be generated either on a one-time basis or periodically for subscription-based services.

Platforms typically have the capability to autonomously generate invoices for their businesses, or to integrate with accounting software platforms to retrieve invoices from there.

Continuous updates on every invoice created by vendors using the payment solution powered by Unipaas are essential. These updates allow us to establish a seamless connection between invoices and transactions on our end, ensuring compliance with regulatory requirements and improved user experience.

Benefits of matching invoices to transactions

Regulatory compliance assurance: Unipaas uses invoice information to stay compliant with relevant financial regulations and industry standards, ensuring a secure and trustworthy payment environment for both your platform and your customers.

Seamless payment collection with Direct Debit: Unipaas leverages invoice data to enable smooth and hassle-free payment collection through Direct Debit, streamlining the payment process for users.

Enhanced user experience: Unipaas aims to clearly display the correlation between payments and corresponding invoices, providing users with enhanced transparency, improved reconciliation and better understanding of their financial activity.

Accurate invoice references at checkout: Unipaas ensures that checkout pages present the correct and up-to-date invoice references, reducing errors and offering a more reliable payment experience to buyers.

Tailored payment options: Leveraging the insights from invoice data, Unipaas is able to offer relevant and appropriate payment methods, differentiating between recurring and one-time invoices to meet diverse user needs effectively.

Invoice endpoint

It is highly recommended to set up automatic forwarding for every invoice to Unipaas whenever it is created or modified on your platform.

Post invoice (one-time or recurring)

Update invoice

---

Post invoice

When to use

Every time a new invoice is created on your platform.

How to use

POST/platform/vendors/{vendorId}/invoices

Posting or updating an invoice can take money

If paymentMethods contains directDebit and customer.reference matches a consumer with an active mandate, the invoice schedules a Direct Debit collection immediately - on POST, and equally when directDebit is added to an existing invoice via PATCH. No further call is required.

A dueDate in the past does not prevent this. The collection is scheduled for the earliest permitted date - approximately five working days ahead - regardless of how old the invoice is. A two-year-old due date and a due date of today both schedule for the same day.

If you are loading historical invoices, or backfilling from another system, do not send directDebit unless you intend to collect those invoices - and do not add directDebit to historical invoices via PATCH for the same reason. Check authorizationId on the response: if it is populated, a collection has been scheduled.

The invoice object

JSON

{
  "reference": "INV-1234",
  "currency": "GBP",
  "totalAmount": 99.5,
  "vatAmount": 19.9,
  "dueDate": "2026-12-12T08:42:52.933Z",
  "paymentMethods":["directDebit"],
  "paymentStatus": "unpaid",
  "totalPaid": 0,
  "customer": {
    "reference": "1234",
    "email": "test@gmail.com",
    "name": "Kevin Malone"
  },
  "lineItems": [
    {
      "description": "line 1",
      "unitPrice": 10.6,
      "quantity": 3
    },
    {
      "description": "line 2",
      "unitPrice": 19.3,
      "quantity": 1
    }
  ],
  "isRecurring": true,
  "subscriptionId": "sub-123",
  "external":false,
  "batchId": "batch-777",
  "publicUrl": "http://yourcompany.com/invoice.pdf",
  "invoiceObject": {}
}

Attributes

Name	Is Required	Type	Description
reference	Yes	String	The invoice number on your system. Must be unique per vendor - a duplicate reference is rejected with 400, so a bulk load or a re-run of the same batch will fail on any repeat.
currency	Yes	String	The currency of the invoice. One of GBP, USD, EUR, or CAD (case-sensitive - lowercase values such as gbp are rejected).
totalAmount	Yes	Number	The total invoice amount
vatAmount	No	Number	The total VAT amount for the invoice (can be 0). If not provided, will be set to 0 by default.
dueDate	Yes	Date	The invoice due date. Use ISO 8601, and for a specific day prefer date-only (2026-12-12), which is stored as midnight UTC. Non-ISO slash and dash formats are parsed as MM/DD/YYYY, not DD/MM/YYYY - so 01/02/2026 is stored as 2 January, and a genuinely UK-formatted value like 13/01/2026 is rejected with 400. A UK-formatted extract will therefore part-succeed on the wrong date and part-fail, so always send ISO 8601. A local time with a UTC offset (for example 2026-12-12T23:30:00+13:00) is converted to UTC, which can shift the stored calendar date - send explicit UTC to avoid this. An invalid calendar date rolls forward rather than erroring: 2026-02-30 is stored as 2 March. For Direct Debit invoices, dueDate determines the collection date, subject to a minimum notice period of approximately five working days and adjustment to the next working day. A due date at or inside that window, including one in the past, is clamped to the earliest permitted date rather than rejected (see the warning above). This raises the stakes on the MM/DD parsing above: a misparsed date now moves money rather than just displaying wrongly.
totalPaid	No	Number	The total amount paid so far on this invoice. If not provided, will be set to 0 by default.
batchId	No	String	The ID of the batch that this invoice was included in.
publicUrl	No	String	A public URL to the invoice PDF version.
lineItems	Yes	Array	Line item object - see table below. The key is required, but an empty array ([]) is accepted.
customer	Yes	Object	Customer object - see table below.
paymentStatus	Yes	Enum	Current invoice payment status: Unpaid = unpaid Paid = paid Partially Paid = partially_paid Refunded = refunded PartiallyRefunded = partially_refunded
paymentMethods	No	Array, Enum	States which payment methods will be available for this specific invoice. For directDebit this field is also an instruction to collect: sending it against an active mandate schedules a Direct Debit collection when the invoice is posted (see the warning above). Available payment methods: apm bankTransfer card creditCard directDebit taxFreeChildcare directDebit is only retained when customer.reference matches a consumer with an active mandate. If there is no active mandate for that consumer, directDebit is silently replaced with the methods configured for your platform and the request still returns 201. Check the response to see whether money is moving, not just what was stored: paymentMethods tells you which methods were kept, and authorizationId tells you whether a collection was scheduled (populated) or not (null).
invoiceObject	No	Object	The invoice object in its original form as created on your platform.
isRecurring	Yes	Boolean	Indicates if this invoice is a recurring one.
external	No	Boolean	Indicates if this invoice was paid using external (non Unipaas). payment method. If value is set to ‘false’ it is an indication that an invoice paid with Unipaas. Default value is set to ‘false’.
subscriptionId	No	String	The recurring invoice subscription identifier.

lineItem attributes:

Name	Is Required	Type	Description
description	Yes	String	A description for a specific line item
unitPrice	Yes	Number	The price of a unit for a specific line item
quantity	Yes	Number	The quantity of a unit for a specific line item

customer attributes:

Name	Is Required	Type	Description
reference	No	String	Platform customer identifier. Optional to the schema, but for Direct Debit to be offered it must match the consumer reference used when the mandate was created.
name	No	String	The customer full name.
id	No	String	Unipaas customer identifier.
email	No	String	The customer email address.

Validation behaviour (applies to both POST and PATCH)

• Types are strict. Numbers and booleans must be sent as their JSON types, not strings - "totalAmount": "99.50" and "isRecurring": "false" are both rejected. Watch for this when the source is a CSV or spreadsheet export.
• There is no cross-field validation. Combinations that do not add up are accepted, for example paymentStatus: "paid" with totalPaid below totalAmount, totalPaid greater than totalAmount, vatAmount greater than totalAmount, line items that do not sum to totalAmount, and partially_paid with totalPaid: 0. Your platform is responsible for keeping these consistent.
• Unknown fields are silently ignored. A misspelled field name returns success and changes nothing, so a typo in a field name does not surface as an error.

Response example

JSON

{
    "id": "6539271a23ebdaa55bae0e4f",
    "merchantId": "6440ca5ec6f5484043645595",
    "vendorId": "64b2acf5e59cc36181291f8d",
    "currency": "GBP",
    "totalAmount": 99.5,
    "totalPaid": 0,
    "vatAmount": 19.9,
    "reference": "INV-1234",
    "publicUrl": "http://yourcompany.com/invoice.pdf",
    "invoiceObject": {},
    "subscriptionId": "sub-123",
    "isRecurring": true,
    "batchId": "batch-777",
    "customer": {
        "reference": "1234567",
        "email": "test@gmail.com",
        "name": "orel reast"
    },
    "lineItems": [
        {
            "description": "line 1",
            "unitPrice": 10.6,
            "quantity": 3
        },
        {
            "description": "line 2",
            "unitPrice": 19.3,
            "quantity": 1
        }
    ],
    "paymentStatus": "unpaid",
    "dueDate": "2022-12-12T08:42:52.933Z",
    "paymentMethods": [
        "directDebit"
    ],
    "external": false,
    "authorizationId": "65392719bd672b26f20d53ca",
    "signedLinkId": "RGJ4_2wLWr",
    "checkoutLink": "https://dev-checkout.unipaas.com/RGJ4_2wLWr/",
    "sessionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjaGFudElkIjoiNjJmYzk5YjI0YzcyOGIzZjAyZmM2MzRmIiwibWVyY2hhbnROYW1lIjoiTmV3IFBsYXRmb3JtIiwiYW1vdW50IjoxMCwiY3VycmVuY3kiOiJHQlAiLCJlbWFpbCI6InVzZXJAdGVzdC5jb20iLCJjb3VudHJ5IjoiR0IiLCJzZWxsZXJJZCI6IjY1MWU2ODRhZDAwNjg5MWIzNWJkZGQ2OCIsInZlbmRvcklkIjoiNjUxZTY4NGFkMDA2ODkxYjM1YmRkZDY4IiwicGhvbmUiOiIrNDQxNjE0OTYwMjU1Iiwic2NvcGVzIjpbIndlYnNka19hY2Nlc3MiLCJkaXJlY3RfZGViaXRfcmVhZCJdLCJpc1JlY3VycmluZyI6ZmFsc2UsImVudiI6ImxvY2FsIiwicGF5bWVudExpbmtJZCI6Ik0zc09laFU1ZEMiLCJpYXQiOjE3MjcwOTc5NTMsImV4cCI6MTcyNzEwMTU1M30.mR_rA3cF5UTANKHcgPVyyfidXg8JieBg_otX6Iz_5V8",
    "createdAt": "2023-10-25T14:32:58.566Z",
    "updatedAt": "2023-10-25T14:32:58.566Z"
}

Name	Type	Description
id	String	The value you obtained in the response to POST request, serves to identify this invoice in Unipaas
authorizationId	String	Populated when a payment has been initiated for this invoice. For a Direct Debit invoice against an active mandate this is set at creation, and GET /pay-ins/{authorizationId} returns the scheduled collection including its collectionDate. Null where no payment has been initiated.
checkoutLink	String	The checkout link for the invoice, which includes the available payment methods for buyer.

Recurring invoices

Report each recurring invoice to the invoice endpoint as it is created, following the instructions provided above, and set isRecurring to true so it is recorded as recurring.

Direct Debit collection depends on an active mandate on the consumer whose reference matches the invoice’s customer.reference. isRecurring does not affect this - without a matching active mandate, directDebit is dropped from paymentMethods regardless of its value.

Where that mandate exists and directDebit is sent, posting the invoice schedules the collection. You do not need to call POST /pay-ins separately for this flow. See the warning above regarding due dates. To set up the mandate, see Implement Direct Debit via API.

---

Update invoice

When to use

1. When an existing invoice has been edited, e.g. changes to the total amount or due date.
2. When an existing invoice has been fully or partially paid.

Flexible checkout modifications require the mandatory use of the PATCH request

If not implemented, vendors won’t be able to make adjustments to the amount, due date, or invoice payment method

The following invoice parameters might affect the payment:

• totalAmount
• totalPaid
• paymentMethods
• paymentStatus
• dueDate

Updating an invoice with a scheduled Direct Debit collection

While a collection is Scheduled, these fields drive it live:

• paymentMethods - adding directDebit schedules a collection. Removing it voids a scheduled one, which is how to cancel a collection you did not intend.
• dueDate - reschedules the collection, subject to the same minimum notice period and working-day adjustment. Note the MM/DD parsing described under dueDate above applies here too, so a non-ISO date will move a live collection to the wrong day.
• totalAmount - changes the amount to be collected.

Check authorizationId on the response and GET /pay-ins/{authorizationId} to confirm the resulting state.

How to use

PATCH/vendors/{vendorId}/invoices/{invoiceId}

The updated invoice object example

You may only update the values that have been changed.

In this example, the invoice was subject to a partial payment of 60 GBP, leading to a change in the payment status, and the payment method was switched by user to Direct Debit.

JSON

{
  "id": "6391fd42a38e34b15b118d9b",
  "totalPaid": 60.0,
  "paymentStatus": "partially_paid",
  "paymentMethods":["directDebit"]
}

Attributes

Name	Is Required	Type	Description
id	No	String	Ignored. The invoice to update is identified solely by the invoiceId in the path; a value sent in the body (or omitted entirely) has no effect.
reference	No	String	The invoice number on your system. Mutable via PATCH. The per-vendor uniqueness constraint still applies, so a rename that collides with another invoice’s reference is rejected.
totalPaid	No	Number	The total amount paid so far on this invoice
totalAmount	No	Number	The total invoice amount. Where a Direct Debit collection is scheduled, this changes the amount to be collected.
dueDate	No	Date	The invoice due date. Where a Direct Debit collection is scheduled, this reschedules it. Same format rules as on POST.
paymentStatus	No	Enum	Current invoice payment status
paymentMethods	No	Array, Enum	States which payment methods will be available for this specific invoice. Available payment methods: apm bankTransfer card creditCard directDebit taxFreeChildcare As on POST, directDebit is only retained when the invoice’s customer.reference matches a consumer with an active mandate.
lineItems	No	Array	Replaces the existing line items wholesale - it does not merge. Sending a single line item discards any items already on the invoice, so always send the full set.

Note

The response body for a PATCH request is the same as for a POST request. The status code differs: PATCH returns 200, whereas POST returns 201.