Invoice endpoint

What is the goal of invoice endpoint?

The invoices endpoint allows platforms to update UNIPaaS about every invoice that is created or updated by users on the platform. Updating UNIPaaS about every invoice created on your platform is critical for UNIPaaS to connect between invoices and transactions.

UNIPaaS will use invoice information for the following:

Show the users on your platform which payment corresponds to which invoice
Present the correct invoice references on checkout pages
Enable relevant payment methods for recurring vs. single invoices

When should you use the invoice endpoint?

We strongly suggest posting every invoice created on your platform to UNIPaaS automatically, at the moment it is created or uploaded by your user.
We also suggest using the PATCH function to update existing invoices once users update them on your platform.

This integration will ensure UNIPaaS is able to connect between payments and invoices, and provide your user with valuable information for their reconciliation.

The invoice object

The following table includes the invoice object fields:

Field name	Is Required	Type	Description
`currency`	Yes	ISO 4217	The currency of the invoice
`totalAmount`	Yes	Number	The total invoice amount
`reference`	Yes	String	The invoice number on your system.
`batchId`	No	String	The id of the batch that this invoice was included in
`vatAmount`	Yes	Number	The total VAT amount for the invoice. (can be 0)
`publicUrl`	No	String	A public URL to the invoice PDF version
`dueDate`	No	Date	The invoice due date
`lineItems`	Yes	an array of `lineItem`	Line item object
`Customer`	Yes	Object	Contains the following fields `id`, `email`, `phone`
`paymentStatus`	Yes	String	Current invoice payment status (Paid, partially paid, etc...)
`invoiceObject`	Yes	Object	Your invoice object
`isRecurring`	Yes	Boolean	Indicates if this invoice is a recurring invoice

The following table includes lineItem object array:

Field 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

Using the invoice endpoint

For every invoices created by a user on your platform, use the following endpoint to POST the invoice to UNIPaaS.

POST/platform/vendors/{vendorId}/invoices

{
  "currency": "GBP",
  "totalAmount": 99.5,
  "reference": "INV-1234",
  "vatAmount": 19.9,
  "batchId": "bt4874583",
  "publicUrl": "http://yourcompany.com/invoice.pdf",
  "dueDate": "2022-12-12T08:42:52.933Z",
  "paymentStatus": "unpaid",
  "lineItems": [
    {
      "description": "line 1",
      "unitPrice": 10.6,
      "quantity": 3
    },
    {
      "description": "line 2",
      "unitPrice": 19.3,
      "quantity": 1
    }
  ],
  "invoiceObject": {},
  "isRecurring": false,
  "customer": {
    "id": "1234",
    "email": "[email protected]",
    "phone": "+447975777666"
  }
}

Response example:

{
  "id": "6391fd42a38e34b15b118d9b", //Used to identify this invoice in UNIPaaS
  "vendorId": "6384b75fc661567cd8b337b5",
  "merchantId": "6384b75fc66156798567898a",
  "currency": "GBP",
  "totalAmount": 99.5,
  "vatAmount": 19.9,
  "reference": "INV-123456",
  "publicUrl": "http://yourcompany.com/invoice.pdf",
  "lineItems": [
    {
      "description": "line 1",
      "unitPrice": 10.6,
      "quantity": 3
    },
    {
      "description": "line 2",
      "unitPrice": 19.3,
      "quantity": 1
    }
  ],
  "invoiceObject": {},
  "isRecurring": false,
  "customer": {
    "id": "1234",
    "email": "[email protected]",
    "phone": "+447975777666"
  },
  "paymentStatus": "unpaid",
  "dueDate": "2022-12-12T08:42:52.954Z",
  "createdAt": "2022-12-12T08:42:52.954Z",
  "updatedAt": "2022-12-12T08:42:52.954Z"
}

To update an existing invoice, use PATCH/platform/vendors/{vendorId}/invoices/{invoicesId}

{
  "id": "6391fd42a38e34b15b118d9b", //Used to identify this invoice in UNIPaaS
  "merchantId": "624c567dfcb8145744c7a881",
  "vendorId": "638498e2c661567cd8b337b3",
  "currency": "GBP",
  "totalAmount": 99.5,
  "vatAmount": 12.23,
  "reference": "INV-1234",
  "publicUrl": "http://yourcompany.com/invoice.pdf",
  "invoiceObject": {},
  "customer": {
    "id": "1234",
    "email": "[email protected]",
    "phone": "+447975777666"
  },
  "lineItems": [
    {
      "description": "line 1",
      "unitPrice": 10.6,
      "quantity": 3
    },
    {
      "description": "line 2",
      "unitPrice": 19.3,
      "quantity": 1
    }
  ],
  "paymentStatus": "unpaid",
  "dueDate": "2022-12-12T08:47:25.450Z",
  "createdAt": "2022-12-12T08:42:26.108Z",
  "updatedAt": "2022-12-12T08:42:26.108Z",
  "correlationId": "e566a2a8-ddf7-4400-99e9-102ee39855df",
  "isRecurring": false
}