# Invoices

### **Product description**

Invoices are a crypto acquiring tool for issuing invoices in crypto or fiat currency. It is also possible to issue invoices with an open amount and open expiration time.

**For each created invoice, the expiration time can be set at your discretion; the maximum lifespan of an invoice is 1 day.**

### **Process description**

To transfer funds for provided products/services to a merchant account, an invoice must be paid.

To make a payment from the Calypso payment form, there are the following steps to be performed:

* Send API request to create an invoice (**POST <https://api.calypso.finance/api/v1/invoice/single/create>**)
* Copy generated invoice ID from the response
* Send API request **POST <https://api.calypso.finance/api/v1/invoice>** and copy the data required for a user to complete this invoice payment
* Add copied data to a payment page and share a page link with a user

Further steps to complete payment are performed by a user in the payment form.

Below is a scheme demonstrating the listed steps.

Names of requests on the scheme indicate certain payment API methods.

<figure><img src="https://1242099714-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlF2vAHahCu7Gtgm1PkXe%2Fuploads%2FGlNDjFj5LyQToozUcrkk%2Fimage.png?alt=media&#x26;token=feb0f60a-8e32-4b03-b44a-3f88e25be924" alt=""><figcaption></figcaption></figure>

### **Underpay handling**

In addition to the Overpay settings, the system applies an internal Underpay threshold of 0.995 (99.5%) for all invoices.

**Example:**

| Invoice amount | Paid amount | Ratio  | Result              |
| -------------- | ----------- | ------ | ------------------- |
| 10.234 USDT    | 10.23 USDT  | 0.9996 | ✅ Success           |
| 10.234 USDT    | 10.00 USDT  | 0.977  | ❌ Intervention flow |

**Important:**

* This rule applies even if the displayed amount on the checkout page is rounded.
* The Underpay threshold is **fixed** and cannot be modified by the merchant.
* This logic is especially relevant for volatile currencies or when network fees cause slight amount variations.

### **Create invoice request example**

**Example of the create invoice request**:

```json
{
  "timestamp": 13292792792,
  "account": "0xc195df92dd9db2a8f28e597981f113d6e7582f8b",
  "payload": {
    "amount": 0.001,
    "currency": "ETH",
    "description": "invoice for client 1",
    "idempotencyKey": "1be6a518-6dcd-477d-96af-dd914b1300ce",
    "type": "SINGLE"
  }
}
```

**Invoice statuses**

Diagram nodes indicate invoice statuses, arrows indicate processes a successful completion of which transfers an invoice from one status to another.

<figure><img src="https://1242099714-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlF2vAHahCu7Gtgm1PkXe%2Fuploads%2FhLJvntoXn3RPRh29uxNW%2F%D0%A1%D0%BD%D0%B8%D0%BC%D0%BE%D0%BA%20%D1%8D%D0%BA%D1%80%D0%B0%D0%BD%D0%B0%202025-11-06%20%D0%B2%2017.43.24.png?alt=media&#x26;token=18d302f0-f826-4e9f-a87b-041513c992ca" alt=""><figcaption></figcaption></figure>

| Status                     | Description                                                                                                                                                                                                                     |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| PENDING\_PAYMENT           | <p>• A new unpaid invoice.<br>• Client has transferred funds, but the funds has not yet been credited to the account.</p>                                                                                                       |
| MEM\_POOL\_FOUND           | Incoming transaction to invoice wallet is found in blockchain mempool.                                                                                                                                                          |
| PENDING\_COMPLIANCE\_CHECK | The transaction was subject to compliance review                                                                                                                                                                                |
| DECLINED                   | The transaction was rejected by compliance                                                                                                                                                                                      |
| PAID                       | Invoice is paid.                                                                                                                                                                                                                |
| PENDING\_INTERVENTION      | <p>• Intervention from the merchant is awaited.<br>• Client transferred insufficient amount.<br>• Client has transferred an amount exceeding an invoice amount.<br>• Funds were transferred from different client accounts.</p> |
| COMPLETED                  | Funds are transferd to merchant wallet.                                                                                                                                                                                         |
| ARCHIVED                   | Invoice is deleted by merchant.                                                                                                                                                                                                 |