> For the complete documentation index, see [llms.txt](https://docs.calypso.money/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.calypso.money/acquiring/invoices/how-to-create-a-invoice-via-api.md).

# How to create a Invoice via API

### **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.money/api/v1/invoice/single/create**](https://api.calypso.money/api/v1/invoice/single/create))
* Copy generated invoice ID from the response
* Send API request **POST** [**https://api.calypso.money/api/v1/invoice**](https://api.calypso.money/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.

### **Invoice "returnUrl" Redirect Status Handling**

Upon redirecting to the `returnUrl`, Calypso appends a query parameter `paymentStatus` to the URL.

**Parameter Values and Behavior:**

* **Successful Payment (COMPLETED status):** Example: `https://merchant.com/checkout?paymentStatus=SUCCESS`
* **Declined or Archived Payment (DECLINED or ARCHIVED status):** Example: `https://merchant.com/checkout?paymentStatus=FAILED`

**Client-Side Handling Logic:**

| `paymentStatus` Value | Expected Page to Display                                                  |
| --------------------- | ------------------------------------------------------------------------- |
| `SUCCESS`             | Success page or order confirmation                                        |
| `FAILED`              | Failed/expired transaction page                                           |
| *absent*              | Treat as a standard redirect to `returnUrl` (no status-specific handling) |

***

### **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.

| 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.                                                                                                                                                                                                 |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.calypso.money/acquiring/invoices/how-to-create-a-invoice-via-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.