# Welcome
The Accounts Payable and Receivable API allows you to scale your finance operations without the complexity of dealing with blockchains and smart contracts.
With the API you can:
* Issue invoices and accept payments in crypto & fiat from your customers
* Track the status of your invoices without polling blockchains or bank accounts
* Create salary payments to pay your employees in crypto & fiat
{% hint style="info" %}
The backbone of the Request Finance API is the Request Network. The Request Network is a decentralized protocol built on Ethereum and maintained by the Request Foundation. For more information on how the two relate to each other, please visit [this page](broken://pages/8Lk8RAjIucyHxtPkDUqO#what-is-the-relation-between-the-request-finance-api-and-the-request-network).
{% endhint %}
# Getting Started
The Request API is organized around REST. It accepts JSON-encoded bodies, returns JSON-encoded responses, and uses standard HTTP response codes and Bearer authentication.
To get started you need an API key. If you have not already done, go to [Request Finance](https://app.request.finance) and create your account for free. You can find your API keys in the ["Developer" tab](https://app.request.finance/account/api-keys) in “Settings”.
## Authentication
All API endpoints are authenticated. The API supports two modes of authentication:
* Using API keys which are great to start working on your project quickly.
* Using OAuth which is more secure and suitable for production. Learn more about going live [here](/going-live).
## Base URL
When using the Request Finance API, please use this URL: .
## Header
All HTTP requests must include the following headers:
* `Accept: application/json`
* `Content-Type: application/json`
* `Authorization: [YOUR_API_KEY]`
The Authorization header is used to authenticate yourself. Please replace `[YOUR_API_KEY]` with your API key.
# Testing
To test the Request Finance API with your application, you can use your “Test” API key when making requests. You can find your “Test” API key in the ["Developer" tab](https://app.request.finance/account/api-keys) in “Settings”.
Invoices that you create using your “Test” API key will be persisted on the Sepolia Testnet (a testing network for Ethereum). You can see and interact with them in our sandbox: . Use your existing credentials to access your sandbox account.
{% hint style="warning" %}
API keys are not recommended for a live application and will be deprecated. Follow the steps in [Going Live](/going-live) instead.
{% endhint %}
## Payments
To test paying an invoice or a payroll payment without spending real tokens, you can use ETH on Sepolia Testnet. You can get some using a faucet online and your wallet address.
Make sure to create invoices and payroll payments with ETH on Sepolia as a payment method.
Since the account that issued the invoice cannot be the account that pays the invoice, you will need to create another Request Finance account for the buyer role.
#### **Test ERC20 tokens**
To test stablecoin payments on Sepolia, we use `FAU` as a `DAI`-pegged testnet token. You can mint some `FAU` tokens by calling use the `mint` function of the `FAU` smart contract:
* Open the `FAU` contract on Etherscan page:
* Click on `Connect to Web3` and pick Metamask
* Metamask will ask you to connect and confirm
* Open the `4. Mint` section
mint function of the FAU smart-contract
* Fill up the `to (address)` field with the address of your wallet (you can find it on top of your Metamask window)
* Insert `10000000000000000000000` for the `value (uint256)`. This is equivalent to `10000 FAU` (with 18 decimals after that).
* Click `Write`, confirm the transaction in Metamask
💡 If you don’t see your `FAU` on Metamask:
* Click on “Don’t see your token? Import tokens”
* Click on “Add custom token” and paste `FAU` contract address: `0x370de27fdb7d1ff1e1baa7d11c5820a324cf623c`
## Postman Collection
You can find a Postman collection of the Request Finance API [here](https://www.postman.com/request-finance/workspace/request-finance-api-public/documentation/24913360-b5105a65-a6bd-4247-b3b1-ed60e5c8f5cb). Feel free to use it to test the API.
# Invoices
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.
{% hint style="info" %}
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](broken://pages/8Lk8RAjIucyHxtPkDUqO#how-do-requests-and-invoices-differ-from-each-other).
{% endhint %}
## Creating an Off-Chain Invoice
## Creates an off-chain invoice for the account
`POST` `https://api.request.finance/invoices`
#### Request Body
| Name | Type | Description |
| -------------------------------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| meta | Request Network JSON Schema |
ISO-8601 representation of the invoice’s creation date.
Default value: Current date
|
| invoiceItems.currency\* | String | Currency code in which the invoice is denominated. For example, invoices can be denominated in USD, but buyers can pay in crypto. |
| invoiceItems.name | String | Name of the product/service for which the invoice is created. |
| invoiceItems.quantity\* | Decimal | Quantity of the product/service that was provided. |
| invoiceItems.tax.type | String |
Can be “fixed” or “percentage”. Required if tax.amount is sent.
Default value: fixed
|
| invoiceItems.tax.amount | Decimal |
Amount of the tax. Required if tax.type is sent.
Default value: 0
|
| invoiceItems.unitPrice\* | Integer | Price of the product/service, excl. taxes. |
| invoiceNumber\* | String | Invoice number. Has to be unique for each invoice. |
| buyerInfo.businessName | String | Business name of the buyer (the customer). |
| buyerInfo.address.streetAddress | String | Street, house, apartment of the buyer. |
| buyerInfo.address.extendedAddress | String | Extended details on the address of the buyer. |
| buyerInfo.address.city.postalCode | String | Post code of the buyer. |
| buyerInfo.address.region | String | Region of the buyer (e.g. “California”). |
| buyerInfo.address.country | String | Two character ISO 3166-1 country code of the buyer. |
| buyerInfo.email\* | String | Email of the buyer. |
| buyerInfo.firstName | String | First name (incl. middle names) of the buyer. |
| buyerInfo.lastName | String | Last name of the buyer. |
| buyerInfo.taxRegistration | String | Tax registration number of the buyer. |
| paymentTerms.dueDate | String | ISO-8601 due date of the invoice. Last date the buyer can pay. |
| paymentOptions\* | Array of objects | Payment configuration. Contains the address which will receive the payment and currencies in which the invoice can be paid. Please review our [Currency API](https://api.request.finance/currency/list/invoicing) for a list of available currencies. |
| note | String | An optional descriptive note. |
| tags | Array of strings | One or multiple tags for an invoice. |
| recurringRule | String |
Used to create a recurring invoice. Input as defined by the ical RFC. Recommended tool: .
In the JSON response, you will get an `id` field. 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.
## Converting an Off-Chain 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
`POST` `https://api.request.finance/invoices/[id]`
#### Path Parameters
| Name | Type | Description |
| ------------------------------------ | ------ | --------------------------- |
| id\* | String | ID of the off-chain invoice |
{% tabs %}
{% tab title="201: Created Request created successfully" %}
```json
{
"id": "63f2f5a7f00a45f276585b28",
"buyerInfo": {
"taxRegistration": "985-80-3313",
"lastName": "Walton",
"firstName": "Justin",
"email": "justin.walton@acme-wholesaler.com",
"businessName": "Acme Wholesaler Ltd.",
"address": {
"streetAddress": "4933 Oakwood Avenue",
"extendedAddress": "",
"city": "New York",
"postalCode": "10038",
"region": "New York",
"country": "US",
"locality": "New York",
"country-name": "US",
"extended-address": "",
"postal-code": "10038",
"street-address": "4933 Oakwood Avenue"
},
"userId": "63c8d2c230d75e750fb449ea"
},
"invoiceItems": [
{
"currency": "USD",
"name": "Television",
"quantity": 2,
"tax": {
"type": "percentage",
"amount": "20"
},
"unitPrice": "9999"
}
],
"paymentTerms": {
"dueDate": "2023-01-21T23:59:59.999Z"
},
"invoiceNumber": "3",
"creationDate": "2022-12-22T14:38:16.916Z",
"meta": {
"format": "rnf_invoice",
"version": "0.0.3"
},
"sellerInfo": {
"email": "joe.bloggs@acme-seller.com",
"address": {
"streetAddress": "4933 Oakwood Avenue",
"extendedAddress": "",
"city": "New York",
"postalCode": "10038",
"region": "New York",
"country": "US",
"locality": "New York",
"country-name": "US",
"extended-address": "",
"postal-code": "10038",
"street-address": "4933 Oakwood Avenue"
},
"businessName": "Acme Corporation",
"firstName": "Joe",
"lastName": "Bloggs",
"taxRegistration": "123456789",
"userId": "63995f77f46a063ba7ac34de"
},
"createdBy": "63995f77f46a063ba7ac34de",
"paymentOptions": [
{
"type": "wallet",
"value": {
"currencies": [
"USDC-matic"
],
"paymentInformation": {
"paymentAddress": "0x4886E85E192cdBC81d42D89256a81dAb990CDD74",
"chain": "matic"
}
}
}
],
"type": "live",
"trackedTransactions": [],
"requestId": "017f7f0b5518c6b3c3711b2f5b4517af10195b0f91dc802c3db36f5bf119595fda",
"invoiceLinks": {
"pay": "https://app.request.finance/017f7f0b5518c6b3c3711b2f5b4517af10195b0f91dc802c3db36f5bf119595fda?token=0x68d6728d52aadb034938d908d8adb93bb12e64e8982c40b4af275c260b3aee97&enablePayment=true",
"view": "https://app.request.finance/017f7f0b5518c6b3c3711b2f5b4517af10195b0f91dc802c3db36f5bf119595fda?token=0x68d6728d52aadb034938d908d8adb93bb12e64e8982c40b4af275c260b3aee97",
"signUpAndPay": "https://app.request.finance/signup?invoice=017f7f0b5518c6b3c3711b2f5b4517af10195b0f91dc802c3db36f5bf119595fda&token=0x68d6728d52aadb034938d908d8adb93bb12e64e8982c40b4af275c260b3aee97&enablePayment=true"
},
"role": "seller",
"tags": [
"my_tag"
]
}
```
{% endtab %}
{% endtabs %}
In the JSON response, you will get a `requestId` field. 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 `invoiceId` for future HTTP requests.
## Sharing your Invoice and Getting Paid
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.
Using the `invoiceLinks.signUpAndPay` link, 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
## Fetching an Invoice
To check the status of an invoice and understand if it has been paid, please poll the endpoint below regularly. Replace `[id]` with the `requestId` of the Request (recommended), or the `invoiceId`.
## Fetch an invoice by its ID
`GET` `https://api.request.finance/invoices/[id]`
#### Path Parameters
| Name | Type | Description |
| ------------------------------------ | ------ | ---------------------------- |
| id\* | String | ID of the request or invoice |
#### Query Parameters
| Name | Type | Description |
| -------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| withLinks=true | String | Includes "Share" and "Payment links" in the response. See |
{% tabs %}
{% tab title="200: OK " %}
```json
{
"id": "63f2f5a7f00a45f276585b28",
"buyerInfo": {
"taxRegistration": "985-80-3313",
"lastName": "Walton",
"firstName": "Justin",
"email": "justin.walton@acme-wholesaler.com",
"businessName": "Acme Wholesaler Ltd.",
"address": {
"streetAddress": "4933 Oakwood Avenue",
"extendedAddress": "",
"city": "New York",
"postalCode": "10038",
"region": "New York",
"country": "US",
"locality": "New York",
"country-name": "US",
"extended-address": "",
"postal-code": "10038",
"street-address": "4933 Oakwood Avenue"
},
"userId": "63c8d2c230d75e750fb449ea"
},
"invoiceItems": [
{
"currency": "USD",
"name": "Television",
"quantity": 2,
"tax": {
"type": "percentage",
"amount": "20"
},
"unitPrice": "9999"
}
],
"paymentTerms": {
"dueDate": "2023-01-21T23:59:59.999Z"
},
"invoiceNumber": "3",
"creationDate": "2022-12-22T14:38:16.916Z",
"meta": {
"format": "rnf_invoice",
"version": "0.0.3"
},
"sellerInfo": {
"email": "joe.bloggs@acme-seller.com",
"address": {
"streetAddress": "4933 Oakwood Avenue",
"extendedAddress": "",
"city": "New York",
"postalCode": "10038",
"region": "New York",
"country": "US",
"locality": "New York",
"country-name": "US",
"extended-address": "",
"postal-code": "10038",
"street-address": "4933 Oakwood Avenue"
},
"businessName": "Acme Corporation",
"firstName": "Joe",
"lastName": "Bloggs",
"taxRegistration": "123456789",
"userId": "63995f77f46a063ba7ac34de"
},
"createdBy": "63995f77f46a063ba7ac34de",
"paymentOptions": [
{
"type": "wallet",
"value": {
"currencies": [
"USDC-matic"
],
"paymentInformation": {
"paymentAddress": "0x4886E85E192cdBC81d42D89256a81dAb990CDD74",
"chain": "matic"
}
}
}
],
"type": "live",
"requestId": "017f7f0b5518c6b3c3711b2f5b4517af10195b0f91dc802c3db36f5bf119595fda",
"status": "open",
"paymentMetadata": {},
"events": [
{
"name": "create",
"userId": "63995f77f46a063ba7ac34de",
"date": "2023-02-20T04:28:12.000Z"
}
],
"trackedTransactions": [],
"role": "seller",
"tags": [
"my_tag"
]
}
```
{% endtab %}
{% endtabs %}
You can check the `status` field 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`
* For Crypto-to-Fiat invoices: the crypto funds arrived at Request Finance's banking partner.
* For externally paid invoices (not paid via Request Finance): 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 Request Finance does not yet support payment detection.
* `paid`
* For Crypto-to-Fiat invoices: the payment was sent to the recipient by Request Finance's banking partners. From here, it will still take some time for the funds to reach the recipient ([see settlement times](https://help.request.finance/en/articles/8622157-how-long-does-it-take-for-a-crypto-to-fiat-payment-to-arrive)).
* For Crypto-to-Crypto invoices: the buyer paid the invoice. Note that the invoice can still move back to `open` if it's marked as unpaid.
* `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 `open` status once the request is actually created.
When the value matches `rejected` or `canceled` you can stop polling for a new status: it means that the invoice has been manually canceled by the payer or the payee respectively, and thus will not get paid.
## Listing Invoices
Fetch a list of the user's invoices. Use the `creationDateRange` parameter to filter for invoices created in a date range. Other filters are listed below for your convenience. For example, the `search=tx_hash` filter is a valuable filter to use when presenting the user with a list of invoices associated with a transaction hash.
## List invoices
`GET` `https://api.request.finance/invoices`
#### Query Parameters
| Name | Type | Description |
| ----------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| take | Integer | How many items should be returned per page. Default: `25`. Maximum: `100`. |
| skip | Integer | Use this filter to paginate the results (= skip to a certain page number). Default: `0`. |
| search | String | Filter by transaction hash, invoice number, company, and other fields. Example: `&search=0xef...` |
| status | String\[] | Filter by invoice status. Available statuses are: `draft`, `pending`, `open`, `paid`, `declaredPaid`, `accepted`, `canceled`, `rejected`, `scheduled`, `overdue`. Example: `&status[]=draft` |
| creationDateRange | String |
Filter by creation date (ISO 8601 format). Example: \&creationDateRange={"from":"2022-06-24T00:00:00.000Z","to":"2022-08-22T00:00:00.000Z"}
|
| variant | String | Filter by invoice format. Use `rnf_invoice` to filter for invoices and `rnf_salary` to filter for salaries. |
| filterBy | String | This filter accepts two values: `sent` or `received` ; returning only invoices sent or received by the user. |
| withLinks | Boolean | Include the "Share" and "Payment links" in the response. Default: `false`. See |
| format | String | You can set the query parameter`&format=paginated` which will return additional information like the total number of results with and without filters, as well as the number of results per invoice status. |
{% tabs %}
{% tab title="200: OK " %}
```json
[
{
"id": "63f3081d8c008a5de554ca97",
"buyerInfo": {
"taxRegistration": "985-80-3313",
"lastName": "Walton",
"firstName": "Justin",
"email": "justin.walton@acme-wholesaler.com",
"businessName": "Acme Wholesaler Ltd.",
"address": {
"streetAddress": "4933 Oakwood Avenue",
"extendedAddress": "",
"city": "New York",
"postalCode": "10038",
"region": "New York",
"country": "US",
"locality": "New York",
"country-name": "US",
"extended-address": "",
"postal-code": "10038",
"street-address": "4933 Oakwood Avenue"
},
"userId": "63c8d2c230d75e750fb449ea"
},
"invoiceItems": [
{
"currency": "USD",
"name": "TV Stand",
"quantity": 1,
"tax": {
"type": "percentage",
"amount": "20"
},
"unitPrice": "2000"
}
],
"paymentTerms": {
"dueDate": "2023-01-21T23:59:59.999Z"
},
"invoiceNumber": "4",
"creationDate": "2022-12-22T14:38:16.916Z",
"meta": {
"format": "rnf_invoice",
"version": "0.0.3"
},
"sellerInfo": {
"email": "joe.bloggs@acme-seller.com",
"address": {
"streetAddress": "4933 Oakwood Avenue",
"extendedAddress": "",
"city": "New York",
"postalCode": "10038",
"region": "New York",
"country": "US",
"locality": "New York",
"country-name": "US",
"extended-address": "",
"postal-code": "10038",
"street-address": "4933 Oakwood Avenue"
},
"businessName": "Acme Corporation",
"firstName": "Joe",
"lastName": "Bloggs",
"taxRegistration": "123456789",
"userId": "63995f77f46a063ba7ac34de"
},
"createdBy": "63995f77f46a063ba7ac34de",
"paymentOptions": [
{
"type": "wallet",
"value": {
"currencies": [
"USDC-matic"
],
"paymentInformation": {
"paymentAddress": "0x4886E85E192cdBC81d42D89256a81dAb990CDD74",
"chain": "matic"
}
}
}
],
"type": "live",
"requestId": "01cb820a384b1e2c4d746a7e6080530f558bb25a211f1e8e7724ea2b6f9fc2789a",
"status": "open",
"role": "seller",
"tags": [
"my_tag"
],
"trackedTransactions": []
},
{
"id": "63f2f5a7f00a45f276585b28",
"buyerInfo": {
"taxRegistration": "985-80-3313",
"lastName": "Walton",
"firstName": "Justin",
"email": "justin.walton@acme-wholesaler.com",
"businessName": "Acme Wholesaler Ltd.",
"address": {
"streetAddress": "4933 Oakwood Avenue",
"extendedAddress": "",
"city": "New York",
"postalCode": "10038",
"region": "New York",
"country": "US",
"locality": "New York",
"country-name": "US",
"extended-address": "",
"postal-code": "10038",
"street-address": "4933 Oakwood Avenue"
},
"userId": "63c8d2c230d75e750fb449ea"
},
"invoiceItems": [
{
"currency": "USD",
"name": "Television",
"quantity": 2,
"tax": {
"type": "percentage",
"amount": "20"
},
"unitPrice": "9999"
}
],
"paymentTerms": {
"dueDate": "2023-01-21T23:59:59.999Z"
},
"invoiceNumber": "3",
"creationDate": "2022-12-22T14:38:16.916Z",
"meta": {
"format": "rnf_invoice",
"version": "0.0.3"
},
"sellerInfo": {
"email": "joe.bloggs@acme-seller.com",
"address": {
"streetAddress": "4933 Oakwood Avenue",
"extendedAddress": "",
"city": "New York",
"postalCode": "10038",
"region": "New York",
"country": "US",
"locality": "New York",
"country-name": "US",
"extended-address": "",
"postal-code": "10038",
"street-address": "4933 Oakwood Avenue"
},
"businessName": "Acme Corporation",
"firstName": "Joe",
"lastName": "Bloggs",
"taxRegistration": "123456789",
"userId": "63995f77f46a063ba7ac34de"
},
"createdBy": "63995f77f46a063ba7ac34de",
"paymentOptions": [
{
"type": "wallet",
"value": {
"currencies": [
"USDC-matic"
],
"paymentInformation": {
"paymentAddress": "0x4886E85E192cdBC81d42D89256a81dAb990CDD74",
"chain": "matic"
}
}
}
],
"type": "live",
"requestId": "017f7f0b5518c6b3c3711b2f5b4517af10195b0f91dc802c3db36f5bf119595fda",
"status": "open",
"paymentMetadata": {},
"events": [
{
"name": "create",
"userId": "63995f77f46a063ba7ac34de",
"date": "2023-02-20T04:28:12.000Z"
}
],
"role": "seller",
"tags": [
"my_tag"
],
"trackedTransactions": []
}
]
```
{% endtab %}
{% endtabs %}
## Approving/Rejecting/Canceling an Invoice
**Approving**:
* *As a buyer*, if you received an invoice from one of your supplier/contractors, you can approve it prior to paying. Approved invoices will show up in the ["Approved" tab of the "Pay" menu](https://app.request.finance/pay/bills?f=approved) in the Request Finance app and indicate that the invoice has been accepted by you and is ready for payment.\
Only `open` invoices can be approved.
* *As a seller*, you cannot approve an invoice. Once a buyer approves your invoice, it will show up in the ["Approved" tab of the "Get paid" menu](https://app.request.finance/get-paid/sent?f=approved).
**Rejecting**
* *As a buyer*, if you received an incorrect invoice from one of your supplier/contractors, you can reject it. Rejected invoices will show up in the ["Rejected" tab of the "Pay" menu](https://app.request.finance/pay/bills?f=rejected) in the Request Finance app and indicate that the invoice has been rejected by you and won't be paid.\
Only `open` and `accepted` invoices can be rejected.
* *As a seller*, you cannot reject an invoice. Once a buyer rejects your invoice, it will show up in the ["Rejected" tab of the "Get paid" menu](https://app.request.finance/get-paid/sent?f=rejected).
**Canceling**:
* *As a seller*, if you issued an invoice to your client but realised a mistake, you can cancel it. Canceled invoices will show in the ["Voided" tab of the "Get paid" menu](https://app.request.finance/get-paid/sent?f=voided).\
Only `open` and `accepted` invoices can be canceled.
* *As a buyer*, you cannot cancel an invoice. Once a seller cancels an invoice, it will show up in the ["Voided" tab of the "Pay" menu](https://app.request.finance/pay/bills?f=voided).
## Approve, reject, cancel an invoice
`POST` `https://api.request.finance/invoices/[id]/changes`
#### Path Parameters
| Name | Type | Description |
| ------------------------------------ | ------ | ----------------- |
| id\* | String | ID of the invoice |
#### Request Body
| Name | Type | Description |
| -------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| type\* | String |
The type of change. Use "accept" to approve an invoice "reject" to reject "cancel" to cancel
|
| input.note\* | String |
Required when rejecting an invoice. Includes a rejection reason.
Example: "input": { note: "Duplicate" }
|
{% tabs %}
{% tab title="200: OK Example response when canceling" %}
```json
{
"id": "646d68bdf64d4a4839eafe25",
"requestId": "0196124706be086a302dfdff2831270120fdc2f5efc5bcf12e48e19082c68fe23c",
"actionType": "cancel",
"input": {},
"networkType": "test",
"chainName": "goerli",
"userId": "63f459c11727622c09b2932a",
"timestamp": "2023-05-24T01:30:37.811Z",
"status": "pending",
"sendNotification": false
}
```
{% endtab %}
{% endtabs %}
## Mark an invoice as paid
`POST` `https://api.request.finance/invoices/[id]/changes`
{% hint style="info" %}
Marking an invoice is paid is useful for invoices that were paid externally (e.g. an external bank transfer). For most regular payments, Request Finance detects the payment automatically, attaches it to the invoice and updates the status to paid.
{% endhint %}
#### Path Parameters
| Name | Type | Description |
| ------------------------------------ | ------ | ----------------- |
| id\* | String | ID of the invoice |
#### Request Body
Name
Type
Description
type*
String
The type of change. Use "declareReceivedPayment" to mark an invoice as paid
# Payroll
Request Finance allows you to pay net salaries, bonuses, or token vestings to your employees with a couple of clicks. With the API, you can create salary payments from your own tool and pay them later via the Request Finance application.
On a technical level, a payroll payment is just another type of [invoice](/invoices). As with invoices, payments also need to be converted to an on-chain request after they are created.
## Creating an Off-Chain Payroll Payment
Creating an off-chain payroll payment is done via the same [endpoint that is used to create invoices](/invoices#creating-an-off-chain-invoice), but with some changes to the attributes (see below).
Note that while the endpoint uses the same attributes, they're handled differently in the Request Finance application. Notably:
* `meta`: `format` must be `rnf_salary` to ensure that the salary payment shows up as such in the Request Finance application.
* A `sellerInfo` object is included that includes information about the employee to be paid.
* Some information can be omitted. Refer to the example request below.
## Creates an off-chain payroll payment
`POST` `https://api.request.finance/invoices`
#### Request Body
| Name | Type | Description |
| -------------------------------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| meta | Request Network JSON Schema |
|
| invoiceNumber\* | String | Payment number. Has to be unique for each payroll payment. |
| invoiceItems.unitPrice\* | Integer | Payroll amount. |
| invoiceItems.quantity\* | Decimal | Quantity. Use `1` for payroll payments. |
| invoiceItems.name | String | Name of the salary, bonus (e.g. Salary - February 2023). |
| invoiceItems.currency\* | String | Currency code in which the payroll payment is denominated. For example, payments can be denominated in USD, but the employee can be paid in crypto. |
| creationDate | String |
ISO-8601 representation of the payment’s creation date.
Default value: Current date
|
| paymentOptions\* | Array of objects | Payment configuration. Contains the address which will receive the payment and currencies in which the salary can be paid. Please review our [Currency API](https://api.request.finance/currency/list/invoicing) for a list of available currencies. |
| paymentTerms.dueDate | String | ISO-8601 due date of the payroll payment. |
| sellerInfo.lastName | String | Last name of the employee. |
| sellerInfo.firstName | String | First name (incl. middle names) of the employee. |
| sellerInfo.email\* | String | Email of the employee who receives the payment. |
| recurringRule | String |
Used to create a recurring payment. Input as defined by the ical RFC. Recommended tool: .
As with invoices, in the JSON response, you will get an `id` field. Please save it in a variable or in your database. You will need it to convert the payment into an on-chain request in the next section.
## Converting an Off-Chain Salary Payment into an On-Chain Request
Converting a salary payment to an on-chain request to make it payable is done using the same [endpoint that is used for invoices](/invoices#converting-an-off-chain-invoice-into-an-on-chain-request). Replace `[id]` with the ID of the payment you saved previously. You don’t need to pass anything in the request body.
## Paying a Salary Payment
The only way to currently pay an on-chain salary payment is via the Request Finance application. Simply log in to [Request Finance](https://app.request.finance/) and navigate to the ["Salaries" menu](https://app.request.finance/salaries) to make payments individually or in batch.
## Fetching a Salary Payment
To check the status of a salary payment and understand if it has been paid, please use the same [endpoint that is used for invoices](/invoices#fetching-an-invoice). Replace `[id]` with the `requestId` of the Request (recommended), or the `invoiceId`.
Example Response
```json
{
"id": "647855dc484f371e737cf593",
"buyerInfo": {
"email": "joe.bloggs@abc-unicorn.com",
"userId": "647804be4e8042efbde7a735"
},
"sellerInfo": {
"email": "william.dean@abc-unicorn.com",
"firstName": "William",
"lastName": "Dean",
"userId": "63c4eeed02a7c1bb872cb3a1"
},
"invoiceItems": [
{
"tax": {
"type": "fixed",
"amount": "0"
},
"currency": "USD",
"quantity": 1,
"unitPrice": "100002",
"name": "Salary"
}
],
"paymentTerms": {
"dueDate": "2023-06-01T14:59:59.999Z"
},
"recurringRule": "DTSTART:20230601T074619Z\nRRULE:FREQ=MONTHLY;INTERVAL=1;COUNT=3",
"invoiceNumber": "1",
"creationDate": "2023-05-31T14:59:59.999Z",
"meta": {
"format": "rnf_salary",
"version": "0.0.3"
},
"nextOccurrence": "2023-07-01T07:46:19.000Z",
"status": "scheduled",
"createdBy": "647804be4e8042efbde7a735",
"paymentOptions": [
{
"type": "wallet",
"value": {
"currencies": [
"USDC-matic"
],
"paymentInformation": {
"paymentAddress": "0x4886E85E192cdBC81d42D89256a81dAb990CDD74",
"chain": "matic"
}
}
}
],
"type": "live",
"miscellaneous": {
"builderId": null,
"createdWith": null,
"logoUrl": null,
"variant": null,
"notifications": {
"creation": true
}
},
"role": "buyer",
"tags": [],
"events": []
}
```
## Listing Salary Payments
To list salaries, use [LIST invoices](/invoices#list-invoices). Make sure to filter for salaries payments in your request;\
`invoices?variant=rnf_salary`.
# Organizations
Users can share their personal account data by inviting team members and assigning them particular roles (Admin, Finance Manager, Accountant, and Approver). Each role comes with specific permissions, which you can find [in our FAQ](https://help.request.finance/en/articles/8622864-what-roles-are-available).
The user holding the account's data is called the **organization owner** and has the same set of permissions as any other admin. The owner of an organization cannot change by design.
To summarize, each user owns a personal account. As soon as they share it with other users by inviting them, it essentially creates an **Organization**.
## Listing Organizations
The following endpoint retrieves the list of organizations a user belongs to. This list does not include the user's account (personal account) but only external organizations that they have been invited to.
{% hint style="warning" %}
**Important**: This endpoint is only available with the OAuth authentication scheme, not API keys. You need to ask for the `user:read` OAuth scope when retrieving a token in order to have access to this endpoint.
{% endhint %}
## List organizations the user belongs to
`GET` `https://api.request.finance/users/organizations`
{% tabs %}
{% tab title="200: OK " %}
```json
[
{
"id": "654b9aaefb9eb1ddde2cf85f",
"name": "acme-org",
"displayName": "Acme Org",
"role": "admin",
"owner": {
"id": "654b9aaa00137146c4fd7e54",
"email": "bills@acme.com",
"firstname": "Bills",
"lastname": "AcmeOrg"
}
}
]
```
{% endtab %}
{% endtabs %}
## Accessing an Organization's Data
When querying Request Finance's API with a user's OAuth token, you will retrieve the user's personal account data.
To access data from an Organization this user belongs to, add the following header to each API call:
```http
X-Organization: [ID]
```
Use the [#listing-organizations](#listing-organizations "mention") API endpoint to retrieve the proper organization ID. For instance:
```http
X-Organization: 654b9aaefb9eb1ddde2cf85f
```
{% hint style="info" %}
If the user is the owner of the organization, you don't need to add the `X-Organization` header. Their personal account itself constitutes the organization; accessing the user's data is like accessing the organization's data.
{% endhint %}
When fetching user's data with the `GET /users` endpoint, the `organization` field corresponds to the organization the user is currently logged in with:
* It is always equal to `X-Organization` when the header is set.
* If the `X-Organization` header is not set, but the user is an owner, then the owned organization is returned.
* If the `X-Organization` header is not set, and the user does not own an organization, the field is set to `null`.
# Clients
{% hint style="warning" %}
This API is only available with OAuth tokens, and requires access from the Request Finance team. Reach out to us via the Intercom widget to discuss your use case.
{% endhint %}
{% hint style="warning" %}
Contrary to invoices, there is no test environment for clients: data is shared between staging and production. Make sure to create a separate Request Finance account to test your integration before deploying it to production.
{% endhint %}
## Retrieving clients
You can list all clients with:
`GET` `https://api.request.finance/clients?type=customer`
#### Query Parameters
| Name | Type | Description |
| ------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| take | Integer | Only available with `&format=paginated`. How many items should be returned per page. Default: `25`. Maximum: `100`. |
| skip | Integer | Only available with `&format=paginated`. Use this filter to paginate the results (= skip to a certain page number). Default: `0`. |
| search | String | Only available with `&format=paginated`. Filter by email or business name. |
| format | String | You can set the query parameter `&format=paginated` to enable search and pagination. It will also return the total number of results. |
Get the details of one client with:
`GET` `https://api.request.finance/clients/[clientId]`
# Document Download (PDF)
Request Finance allows you to download PDFs of your invoices via API, just as you can download them via the interface.
### Request a PDF
`GET` `https://api.request.finance/invoices/[id]/pdf/[type]`
{% hint style="info" %}
This endpoint does not support bulk downloads. Retrieve each invoice PDF individually, or loop through IDs to automate the process.
{% endhint %}
#### Path Parameters
| Name | Type | Description |
| -------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id\* | String | ID of the request or invoice |
| type\* | String |
Either default or receipt
default: the invoice as a PDF
receipt: the invoice receipt, only available for paid invoices
|
# Webhooks
Request Finance API - Webhooks Documentation
## Introduction
Webhooks in Request Finance allow you to receive real-time notifications about changes to invoices, such as when they are created, accepted, canceled, rejected, or paid. This guide explains how to set up and secure webhooks for your integration with the Request Finance API.
## Prerequisites
1. **Create an OAuth app:** See [Going Live](/going-live#authentication)
2. **Whitelist Your Account**: Before you can use webhooks, you need to be whitelisted for the feature. Contact Request Finance support to request access.
## Setting Up Webhooks
### Step 1: Add Webhook URL and Secret
Once your account is whitelisted, follow these steps to add your webhook URL and secret:
1. Navigate to the `Settings > Developer > Apps` page in the Request Finance dashboard.
2. Create or edit your OAuth application.
3. Enter your webhook URL.
4. Enter your webhook secret. This secret is used to verify the integrity of the incoming requests.
The webhook URL and secret are mandatory for events to be sent to your URL.
Edit your OAuth app, and add the webhook URL and secret
### Step 2: Verify Webhook Setup
To ensure that your webhooks are working correctly, you can use testing services like [Webhook.site](https://webhook.site) or [Webhook Test](https://webhook-test.com/). These services allow you to inspect the incoming webhook requests and verify their format.
## Webhook Events
When an event occurs, Request Finance will send a JSON payload to your webhook URL. The payload format is as follows:
```json
{
"variant": "rnf_invoice", // Other possible values: rnf_salary
"event": "create", // Other possible values: accept, cancel, reject, paid
"timestamp": 1720605600000, // Unix timestamp in milliseconds
"invoice": {
...
}
}
```
The `invoice` object is similar to the one received by the `GET /invoices/:id` API, see [Invoices](/invoices#fetch-an-invoice-by-its-id).
### Event Sources
Depending on the usage of your OAuth application, you will receive events for different types of invoices:
* If your OAuth application is not yet used for interracting with the Request Finance API, you will still receive webhook events for every invoice sent or received by your account or organization.
* If your OAuth application follows the [Authorization Code Flow](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow) and is used to read users' data, you will receive webhook events for every invoice sent or received by users who have authorized your application.
* If your OAuth application follows the [Client Credentials Flow](https://auth0.com/docs/get-started/authentication-and-authorization-flow/client-credentials-flow) and sends invoices, you will receive webhook events for every invoice it creates.
### Event Types
The `event` field can have the following values:
* `create`: When an invoice is created.
* `accept`: When an invoice is accepted (by the buyer).
* `cancel`: When an invoice is canceled (by the seller).
* `reject`: When an invoice is rejected (by the buyer).
* `declareSentPayment`
* For Crypto-to-Fiat payments: sent when the funds arrive at Request Finance's banking partner.
* For externally-paid payments (not paid via Request Finance): the payable was manually marked as paid by the payer
* `declareReceivedPayment`
* For Crypto-to-Fiat payments: the payment was sent to the recipient by Request Finance's banking partners. From here, it will still take some time for the funds to reach the recipient ([see settlement times](https://help.request.finance/en/articles/8622157-how-long-does-it-take-for-a-crypto-to-fiat-payment-to-arrive)).
* For externally-paid payments (not paid via Request Finance): the recipient declared the payment as received.
* `paid`
* For Crypto-to-Fiat payments: same as `declareReceivedPayment`, both events happen consecutively and have the same meaning.
* For Crypto-to-Crypto payments: the payment was settled on-chain and funds are in the recipient's wallet.
{% hint style="info" %}
**Crypto-to-Fiat payment bounce**
Crypto-to-Fiat payments can be returned, for instance, due to incorrect bank details. In this case, a `open`/`accepted` webhook is sent.
{% endhint %}
## Securing Your Webhooks
To ensure that the webhook requests are legitimate and not coming from unauthorized sources, you should verify the `X-Webhook-Signature` HTTP header sent with each event. This header contains the SHA256 signature of the request body, generated using your webhook secret.
### Verification Example in Node.js
Here's an example of how to verify the webhook signature in Node.js:
```javascript
const crypto = require('crypto');
// Your webhook secret
const secret = 'your_webhook_secret';
// The raw body of the webhook event (as a string)
const body = '{"variant":"rnf_invoice","event":"create","timestamp":"2024-07-10T10:00:00Z","invoice":{...}}';
// The signature from the X-Webhook-Signature header
const signature = req.headers['x-webhook-signature'];
// Create the HMAC
const hmac = crypto.createHmac('sha256', secret);
hmac.update(body);
const digest = hmac.digest('hex');
// Compare the generated HMAC digest with the signature
if (digest === signature) {
console.log('Webhook signature is valid.');
} else {
console.log('Invalid webhook signature.');
}
```
# Going Live
## Prerequisite
Before going live, make sure you have read the page about [Organizations](/organizations). It's important to handle the case where your users' data resides in an organization vs. their personal account.
## Security notice
> **You MUST create separate Request Finance accounts for your TEST/DEV and PRODUCTION OAuth applications.**
User settings, including email, password, 2FA configuration, and OAuth applications, can be managed from either:
* Prod - [app.request.finance](https://app.request.finance/)
* Staging - [baguette-app.request.finance](https://baguette-app.request.finance/)
These settings are shared across environments. The same OAuth application gives you access to both environments.
Do not host all your OAuth applications under the same Request Finance account unless absolutely necessary. If you have to, you must protect your **DEV** and **TEST** client secrets with the same level of security as your **PRODUCTION** client secret. For example:
* Never store client secrets in plain text.
* Restrict secret access to authorized personnel only.
* Use a secure secret management solution.
## Authentication
Replace API keys with the more secure OAuth authentication to go live with your application. Please follow these steps:
1. If you intend to act on your users' behalf, we advise setting up an account just for the integration, one that does not send or receive invoices, with a strong password that can be archived safely. (more info in 4.1)
2. You need to be authorized to access the Apps section, reach out to us with the integration account's email: [here](mailto:support@request.finance) or via the Intercom chat.
3. Create an app in your Request Finance account on the ["Developers" menu](https://app.request.finance/developers/apps). Please read [#security-notice](#security-notice "mention") before creating any app.
4. Retrieve the access and refresh tokens from the provided Client Secret and Client ID:
1. If you act on your users' behalf (ex: you are reading your users' invoices), follow the [Authorization Code Flow](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow). You can use any OAuth2 or OpenID-compatible library to do the heavy lifting. Auth0 also provides its [own libraries here](https://auth0.com/docs/quickstart/webapp); choose any package corresponding to your language under "Regular Web App." For reference, we developed two implementation examples, one using NextJS and one using ExpressJS, available on this [demo repository](https://github.com/RequestFinance/demo-api).
2. If you act on your account's behalf (ex: you are sending invoices from your account to external users), you will need to follow the [Client Credentials Flow](https://auth0.com/docs/get-started/authentication-and-authorization-flow/client-credentials-flow). Reach out to us first to activate this flow. Note that you can only use one type of OAuth flow per app. You can find an example of how to implement it [here](https://auth0.com/docs/get-started/authentication-and-authorization-flow/client-credentials-flow/call-your-api-using-the-client-credentials-flow#example-post-to-token-url). This flow only contains an access token (no refresh token), so you don't need to use the `offline_access` scope in the next step.
5. To configure the OAuth connection, you need to use the following parameters:
```
URL: https://auth.request.finance
Audience: accounts
Scope: openid profile email offline_access
```
Other scopes are also available, like `user:read`, see [Organizations](/organizations#list-organizations-the-user-belongs-to).
6. Save the access token and, in case of Authorization Code Flow, the refresh token too. Authenticate your API calls using the access token and reuse it until it expires (24 hours). After it expires, use the refresh token to ask for a new access token, or, in the case of Client Credential Flow, use your app secret to ask for a new access token. Here is an example of how to use the access token with NodeJS. Notice the mandatory `X-Network` header. Its values are either `test` or `live`.
{% code fullWidth="false" %}
```json
fetch("https://api.request.finance/invoices", {
headers: {
Authorization: `Bearer ${accessToken}`,
"X-Network": "live",
},
})
```
{% endcode %}
## Optional: Transactional Emails
{% hint style="info" %}
Transactional Emails require OAuth authentication as described above.
{% endhint %}
By default, we don't send transactional notifications for invoices created via API. If your users create invoices through your integration, you probably want issuers to be alerted of new invoices, and other transactional emails to be sent. In such case, please get in touch [here](mailto:support@request.finance) or via the Intercom chat, and share your Client ID with the Request Finance team.
## Troubleshooting
### User does not have the right scope
If you are missing a scope for a given user (this can be verified by checking the issued `access_token` on ), you can add `prompt=consent` to the authorization URL to force updating the allowed scopes.
For instance, if you cannot get a `refresh_token` for a specific user, that user might miss the `offline_access` scope.
### OIDC-Conformant Authentication
As of May 2026, we have adopted OIDC-conformant authentication. This introduces several structural changes to authentication requests, authentication responses, ID tokens, and access tokens. Notable changes include:
* `response_type=token` now only returns an access token. To receive an ID token, use `response_type=id_token` or `response_type=token id_token`.
* ID tokens are now signed asymmetrically using the `RS256` algorithm.
* Authentication requests that do not include a `nonce` parameter will be rejected. For additional guidance, see [*Mitigate Replay Attacks When Using Implicit Flow*](https://auth0.com/docs/get-started/authentication-and-authorization-flow/implicit-flow-with-form-post/mitigate-replay-attacks-when-using-the-implicit-flow).
* Refresh tokens are no longer returned when using the Implicit Flow for authentication.
Please review your integrations to ensure they are compatible with these updated OIDC requirements.
# Rate Limits
"What rate limits do you have on the API?"
The following rate limits apply globally:
* Unauthenticated users: 500 calls/hour
* Authenticated users: 5000 calls/hour
* Applications using [OAuth authentication](/going-live): 15000 calls/hour
Additionally, some endpoints have stricter rate limiting. The API always returns the following information in the headers:
* `X-Rate-Limit-Limit`: the rate limit ceiling for that given endpoint
* `X-Rate-Limit-Remaining`: the number of requests left for that given endpoint
* `X-Rate-Limit-Reset`: the remaining time window before the rate limit resets, in seconds
We also send a `Retry-After` in the header on blocked requests to let you know when to call the endpoint again.
# Currencies
"Which currencies and networks do you support?"
The list of currencies accepted by our API is here:\
You can find the list of chains here:
Alternatively, please refer to [this page](https://help.request.finance/en/articles/8650043-supported-currencies-and-networks) for a readable format of the currencies and networks supported.