Invoice endpoint with vendor Reference

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:

1. Collect payments with Direct Debit
2. Show the users on your platform which payment corresponds to which invoice
3. Present the correct invoice references on checkout pages
4. 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:

The following table includes lineItem object array:

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/invoices

{
  "currency": "GBP",
  "totalAmount": 99.5,
  "totalPaid": 40.5,
  "reference": "INV-1234",
  "vendorReference": "134234",
  "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":["cardNumber"],//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",
  "vendorReference": "134234",
  "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":["bankTransfer"],//optional
  "customer": {
    "reference": "1234",
    "email": "[email protected]",
    "phone": "+447975777666"
  }
}