To get paid in cryptocurrency, you first need to create an invoice, which includes details on the buyer, the product or service purchased, the price, taxes, and how you would like to get paid.
After creating the invoice off-chain, it needs to be converted into an on-chain request using another endpoint introduced further below.
The Request Network protocol is all about creating payment requests. They are stored on-chain. Invoices are what you will be manipulating with the Request Finance API. Invoices are simply an implementation of requests with a predefined schema for their content. If you wish to learn more about this, please visit this page.
Creates an off-chain invoice for the account
Let’s assume you sold 2 TVs, each worth $99.99, to your customer, Acme Wholesaler Ltd. on the 22nd of December 2022. The tax is 20%, so that’s $119.99 including tax. The total invoice amount will thus be $239.98 (=2x $119.99) and it’s payable by the 21st of January 2023.
Your contact at Acme Wholesaler Ltd. is Justin Walton, so you want to send the invoice to his email address, [email protected]
Finally, you want to be paid in USDC on Polygon.
To create an invoice for this, you would pass the following body with the request:
"businessName": "Acme Wholesaler Ltd.",
"streetAddress": "4933 Oakwood Avenue",
"city": "New York",
"region": "New York",
"email": "[email protected]",
In the JSON response, you will get an
idfield. Please save it in a variable or your database. In the next section, you will need it to convert the invoice into an on-chain request.
To make an invoice payable, it must be converted to an on-chain request. Once the invoice is created, convert it into an on-chain request using the endpoint below. Replace
[id]with the ID of the invoice you saved previously. You don’t need to pass anything in the request body.
Converts off-chain invoice into on-chain request
In the JSON response, you will get a
requestIdfield. 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. You may use this value in place of the
invoiceIdfor future HTTP requests.
To get paid by your customer, you need to redirect them to a payment page hosted by Request Finance. You can get the links to the payment page from the response after creating an on-chain request and embed them in your application or an email.
invoiceLinks.signUpAndPaylink, you can redirect your customers to a page that looks like the one below, where they can pay your invoice or sign into their Request Finance account, if they have one.
When your customers pay through this page using Request Finance, they can enjoy the convenience and security of our platform, which includes measures to prevent accidental double payments. Additionally, this payment method ensures that the invoice status is automatically updated, simplifying invoice tracking for both you and your customers.
Sign up & pay page
To check the status of an invoice and understand if it has been paid, please poll the endpoint below regularly. Replace
requestIdof the Request (recommended), or the
Fetch an invoice by its ID
You can check the
statusfield of the JSON response. The different statuses of an invoice are the following:
open– The request associated with the invoice has been created on-chain. The buyer has not yet paid the invoice.
accepted– The invoice has been approved by the buyer.
declaredPaid– The buyer declared the invoice as paid. The seller has to confirm before the invoice can move into the paid status. This is necessary for currencies, where the Request Network does not yet support payment detection.
paid– Final state. The buyer paid the invoice.
canceled– Final state. The seller canceled the invoice.
rejected– Final state. The buyer rejected the invoice.
scheduled– Status for recurring invoices. Indicates that an invoice will be created on a specific date in the future.
draft– The invoice is in draft status. It can still be edited and was not yet converted into an on-chain request. This status is currently only supported when creating an invoice in the Request Finance UI.
When creating an on-chain request with the previously described process, you should end up with a pending status while the request is being persisted on-chain (this process is asynchronous), followed by an
openstatus once the request is actually created.
You can use the value
paidto classify the Request as "fulfilled" and stop polling for a new status.
When the value matches
canceledyou can also stop polling: it means that the request has been manually canceled out by the payer or the payee respectively, and thus will not get paid.
Fetch a list of the user's invoices. Use the
creationDateRangeparameter to filter for a invoices created in a date range. Other filters are listed below for your convenience, for example the
search=tx_hashfilter is a useful filter to use when presenting the user with a list of invoices associated with a transaction hash.