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

NameIs RequiredTypeDescription
referenceYesStringThe invoice number on your system.
currencyYesISO 4217The currency of the invoice
totalAmountYesNumberThe total invoice amount
vatAmountNoNumberThe total VAT amount for the invoice (can be 0).
If not provided, will be set to 0 by default.
dueDateYesDateThe invoice due date.
totalPaidNoNumberThe total amount paid so far on this invoice.
If not provided, will be set to 0 by default.
batchIdNoStringThe ID of the batch that this invoice was included in.
publicUrlNoStringA public URL to the invoice PDF version.
lineItemsYesArray Line item object - see table below.
consumerYesObjectCustomer object - see table below.
paymentStatusYesEnumCurrent invoice payment status:
Unpaid = unpaid
Paid = paid
Partially Paid = partially_paid
Refunded = refunded
PartiallyRefunded = partially_refunded
paymentMethodsNoArray, EnumStates 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
invoiceObjectNoObjectThe invoice object in its original form as created on your platform.
isRecurringYesBooleanIndicates if this invoice is a recurring one.
externalNoBooleanIndicates 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'.
subscriptionIdNoStringThe recurring invoice subscription identifier.

lineItem attributes:

NameIs RequiredTypeDescription
descriptionYesStringA description for a specific line item
amountYesNumberA price of a unit for a specific line item
quantityYesNumberThe quantity of a unit for a specific line item

customer attributes:

NameIs RequiredTypeDescription
referenceYesStringPlatform customer identifier.
nameYesStringThe customer full name.
idNoStringUNIPaaS customer identifier.
emailNoStringThe 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/",
    "createdAt": "2023-10-25T14:32:58.566Z",
    "updatedAt": "2023-10-25T14:32:58.566Z"
}
NameTypeDescription
idStringThe value you obtained in the response to POST request, serves to identify this invoice in UNIPaaS
checkoutLinkStringThe 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

  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

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

NameIs RequiredTypeDescription
idYesStringThe value you obtained in the response to POST request, serves to identify this invoice in UNIPaaS
totalPaidNumberThe total amount paid so far on this invoice
paymentStatusEnumCurrent invoice payment status
paymentMethodsArray,
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