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

The invoice object

{
  "reference": "INV-1234",
  "currency": "GBP",
  "totalAmount": 99.5,
  "vatAmount": 19.9,
  "dueDate": "2022-12-12T08:42:52.933Z",
  "paymentMethods":["directDebit"],
  "paymentStatus": "unpaid",
  "totalPaid": 0,
  "customer": {
    "reference": "1234",
    "email": "[email protected]",
    "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.
`currency`	Yes	ISO 4217	The currency of the invoice
`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.
`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.
`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. Note:* If Direct Debit is selected, the invoice cannot be paid with UNIPaaS in any other method. Available Payment Methods: `creaditCard` `bankTransfer` `directDebit` `offlineBankTransfer` `paypal` Important - when the Invoice UI Web-Embed is not implemented (e.g., in the recurring payment flow), it is critical to send this parameter with `directDebit` for every recurring payment if Direct Debit is to be used to collect the payment. Based on platform configuration
`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
`amount`	Yes	Number	A 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`	Yes	String	Platform customer identifier.
`name`	Yes	String	The customer full name.
`id`	No	String	UNIPaaS customer identifier.
`email`	No	String	The customer email address.

Response example

{
    "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": "[email protected]",
        "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
`checkoutLink`	String	The checkout link for the invoice, which includes the available payment methods for buyer.

Recurring invoices

To enable UNIPaaS handling recurring invoices effectively, please ensure the following:

Automatically report each invoice created in the recurring mechanism to the invoice endpoint, following the instructions provided above.
Set the paymentMethods parameter to the desired values. For example, if Direct Debit is the preferred payment method, assign directDebit to each invoice.
Set isRecurring parameter to true.

It is important to implement these steps; otherwise, UNIPaaS will not be able to identify the created invoices as recurring, resulting in a lack of clarity regarding the appropriate payment method to be used.

Update invoice

When to use

When an existing invoice has been edited, e.g. changes to the total amount or due date.
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

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.

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

Attributes

Name	Is Required	Type	Description
`id`	Yes	String	The value you obtained in the response to POST request, serves to identify this invoice in UNIPaaS
`totalPaid`		Number	The total amount paid so far on this invoice
`paymentStatus`		Enum	Current invoice payment status
`paymentMethods`		Array, Enum	States which payment methods will be available for this specific invoice. Available Payment Methods: `creaditCard` `bankTransfer` `directDebit` `offlineBankTransfer` `paypal`

⚙️
The response for a PATCH request will be the same as that for a POST request