Invoices
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)
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, assigndirectDebit
to each invoice. - Set
isRecurring
parameter totrue
.
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
Updated 2 months ago