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:

Collect payments with Direct Debit
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.

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
`totalPaid`	No	Number	The total amount paid so far on this invoice
`reference`	Yes	String	The invoice number on your system.
`batchId`	No	String	The id of the batch that this invoice was included in
`vatAmount`	No	Number	The total VAT amount for the invoice (can be 0). If not provided, will be considered to be 0.
`publicUrl`	No	String	A public URL to the invoice PDF version
`dueDate`	No	Date	The invoice due date
`lineItems`	Yes	Array	Line item object - see table below
`Customer`	Yes	Object	Contains the following fields `id`, `email`, `phone`
`paymentStatus`	Yes	String	Current invoice payment status (Paid, partially paid, etc...)
`paymentMethods`	No	Array	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: directDebit, creditCard, bankTransfer, noOption 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`	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,
  "totalPaid": 40.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,
  "paymentMethods":["bankAndCard"],//optional
  "customer": {
    "reference": "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,
  "totalPaid": 40.5,
  "vatAmount": 19.9,
  "reference": "INV-1234",
  "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,
  "paymentMethods":["bankAndCard"],
  "customer": {
    "reference": "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"
}

Handling recurring (repeat) invoices

Make sure that each invoice created in the recurring mechanism is reported to the invoice endpoint as instructed above.
paymentMethods parameter should be set to the desired values. E.g., if Direct Debit is desired as a payment method, set each invoice to directDebit.
isRecurring parameter should be set to true.

Without the above, UNIPaaS will not identify the created invoices as recurring ones and will not know which payment method should be used for them.

Update invoice

When a change is made to an existing invoice (e.g., invoice amount or due date), it is important to update the invoice with the PATCH function. The following parameters will potentially affect the payment:

totalAmount - changing this will update the checkout and Direct Debit collection amount (if Direct Debit was used).
totalPaid - changing this will update the checkout and Direct Debit collection amount (if Direct Debit was used).
paymentMethods - changing this will update the checkout and the required payment method for the invoice..
paymentStatus
dueDate

🚧
Using the PATCH function is mandatory for enabling Direct Debit
Without implementing, the vendor will not be able to make changes to the amount, due date or payment method of the payment.

Request example:

{
  "id": "6391fd42a38e34b15b118d9b", //Used to identify this invoice in UNIPaaS
  "currency": "GBP",
  "totalAmount": 99.5,
  "totalPaid": 60,
  "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,
  "paymentMethods":["bankAndCard"],//optional
  "customer": {
    "reference": "1234",
    "email": "[email protected]",
    "phone": "+447975777666"
  }
}