You are now familiar with the Request API, but did you know you could also create, on Portal, invoices which supersede requests?
Invoices are simply an implementation of requests with a predefined schema for the
Invoices are mainly used by the Request Finance application
as a way to practically represent general invoicing data.
Invoice API also differ by the layer of automation added on top of Request API. Whenever an invoice is created, it is possible to have an email sent to the designated payer. The invoice issuer (payee) can also get notified as soon as the corresponding request has been paid (please contact us if you need more info on this feature).
Knowing if a Request has been paid is not trivial.
But invoices have an additional property: a
; so knowing if the underlying Request has been paid is as easy as reading this property.
Invoices can also be scheduled to create occurrences at regular intervals. This is useful to manage collaborators salaries.
|Portal API endpoint|
not validated by API
|Invoices extend requests|
In this tutorial we will learn how to use the invoice API to create off-chain invoices, and then transform those invoices into on-chain requests.
Please follow the Portal Introduction to retrieve an API key. Reminder: all HTTP requests must include the following headers:
The Authorization header is used to authenticate yourself.
[YOUR_API_KEY] with the previously retrieved key.
Use the following endpoint first to create an off-chain invoice that will later be converted to an on-chain Request:
In the body part you can use the following example and replace the data accordingly:
In the JSON response you will get an
id field. Please save it in a variable or in your database.
You will need it in the next section.
Use the following endpoint to convert the previously created off-chain invoice to an on-chain Request:
; and replace
[id] with the previously saved invoice ID.
You don't need to pass anything in the request body this time.
In the JSON response you will get a
This is the ID of the newly created Request.
Please save it in your database as you will need it to be informed of when the Request has been paid.
In order to be informed as to when the payer has fulfilled the Request you need to poll our API regularly.
Please use the following endpoint to retrieve the status of the Request:
[id] with the ID of the invoice, or the ID of the Request
You can check the
status field of the
JSON response. The different statuses of an invoice are the following:
After creating the Request with the previously described process you should end-up with a
while the Request is being created on-chain (as this process is asynchronous),
followed by an
open status after the Request has actually been created.
You can use the value
paid to classify the Request as "fulfilled" and stop polling for a new status.
When the value matches
canceled you can also stop polling because
it means that the Request has been manually canceled out by the payer (or the payee via it's interface),
and thus will not get paid.
You should also terminate the polling process if the current date exceeds