# Invoice Creation

In order to create an invoice, you need to send a POST request.

### What the method allows you to do

* Creates a unique invoice
* Returns a payment link or payment details
* Allows you to pass additional data

### Endpoint

<mark style="color:green;">`POST`</mark> `https://api.cryptocloud.plus/v2/invoice/create`

### Headers

| Name                                            | Type   | Example                             | Description     |
| ----------------------------------------------- | ------ | ----------------------------------- | --------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Token eyJ0eXAiOiJK<...>4npi1ksS8tSY | Project API key |

### Request Body

Key parameters

| Name                                       | Type   | Example           | Description                                                                                                                                                                                                                 |
| ------------------------------------------ | ------ | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| shop\_id<mark style="color:red;">\*</mark> | string | NGpD44<...>KXRdQ  | Unique identifier of the store from personal account                                                                                                                                                                        |
| amount<mark style="color:red;">\*</mark>   | float  | 100               | Payment amount in USD                                                                                                                                                                                                       |
| currency                                   | string | USD               | <p>Available conversion currencies:</p><p></p><p>USD, UZS, KGS, KZT, AMD, AZN, BYN, AUD, TRY, AED, CAD, CNY, HKD, IDR, INR, JPY, PHP, SGD, THB, VND, MYR, RUB, UAH, EUR, GBP.</p><p></p><p>The default currency is USD.</p> |
| order\_id                                  | string | ORDER\_93223      | Custom invoice number in the external system                                                                                                                                                                                |
| email                                      | string | <email@gmail.com> | Payer’s email address                                                                                                                                                                                                       |

Optional parameters

**add\_fields** — an object for passing additional data

| Name        | Type | Example                                                                     | Description           |
| ----------- | ---- | --------------------------------------------------------------------------- | --------------------- |
| add\_fields | dict | <p>{time\_to\_pay: {</p><p> "hours": 24, "minutes": 0</p><p> },</p><p>}</p> | Additional parametres |

{% hint style="warning" %}
Optional parameters must be passed within the **add\_fields** object.
{% endhint %}

<table data-full-width="false"><thead><tr><th width="215">Name</th><th width="175.8984375">Type</th><th width="193.6492919921875">Example</th><th width="196">Description</th></tr></thead><tbody><tr><td>time_to_pay</td><td>dict</td><td>{ "hours": 24, "minutes": 0 }</td><td>Invoice lifetime</td></tr><tr><td>available_currencies</td><td>list[string]</td><td>[ "USDT_TRC20", "ETH", "BTC" ]</td><td><p>Available payment currencies:<br></p><p>BTC, LTC, TRX, SOL, TON, BNB, ETH, ETH_ARB, ETH_BASE, ETH_OPT, USDT_ARB, USDT_BSC, USDT_ERC20, USDT_OPT, USDT_SOL, USDT_TON, USDT_TRC20, USDC_ARB, USDC_BASE, USDC_BSC, USDC_ERC20, USDC_OPT, USDC_SOL, DAI_ARB, DAI_BASE, DAI_BSC, DAI_ERC20, DAI_OPT, USDD_TRC20, PYUSD_ERC20, PYUSD_SOL, XAUT_ERC20, XAUT_TON, ARB_ARB, OP_OPT, PEPE_BSC, PEPE_ERC20, SHIB_BSC, SHIB_ERC20, TRUMP_SOL</p></td></tr><tr><td>cryptocurrency</td><td>string</td><td>ETH</td><td><p>Selecting the payment currency on behalf of the user.<br></p><p>If a currency is specified, the payment page will display the payment details without a currency selection option.<br></p><p>The address and amount will also be returned in the API response.</p></td></tr></tbody></table>

### Request examples

These examples show how to send a request to create an invoice. Note that you must provide your API key in the `Authorization` header to successfully authorize the request.

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST \
     -H "Authorization: Token <API KEY>" \
     -H "Content-Type: application/json" \
     -d '{"amount": 100, "shop_id": "xBAivfPIbskwuEWj", "currency": "USD"}' \
     "https://api.cryptocloud.plus/v2/invoice/create"
```

{% endtab %}

{% tab title="Python" %}

```python
import requests
import json

url = "https://api.cryptocloud.plus/v2/invoice/create"
headers = {
    "Authorization": "Token <API KEY>",
    "Content-Type": "application/json"
}

data = {
    "amount": 100,
    "shop_id": "xBAivfPIbskwuEWj",
    "currency": "USD"
}

response = requests.post(url, headers=headers, json=data)

if response.status_code == 200:
    print("Success:", response.json())
else:
    print("Fail:", response.status_code, response.text)
```

{% endtab %}

{% tab title="JavaScript " %}
{% code title="Fetch.js:" %}

```javascript
const url = 'https://api.cryptocloud.plus/v2/invoice/create';
const headers = new Headers({
    'Authorization': 'Token <API KEY>',
    'Content-Type': 'application/json'
});
const data = {
    amount: 100,
    shop_id: 'xBAivfPIbskwuEWj',
    currency: 'USD'
};

fetch(url, {
    method: 'POST',
    headers,
    body: JSON.stringify(data)
})
.then(response => {
    if (response.ok) {
        return response.json();
    } else {
        return Promise.reject('Creation Error');
    }
})
.then(data => {
    console.log('Success:', data);
})
.catch(error => {
    console.error('Fail:', error);
});
```

{% endcode %}

{% code title="Ajax.js:" %}

```javascript
$.ajax({
    url: 'https://api.cryptocloud.plus/v2/invoice/create',
    method: 'POST',
    headers: {
        'Authorization': 'Token <API KEY>',
        'Content-Type': 'application/json'
    },
    data: JSON.stringify({
        amount: 100,
        shop_id: 'xBAivfPIbskwuEWj',
        currency: 'USD'
    }),
    success: function(data) {
        console.log('Success:', data);
    },
    error: function(error) {
        console.error('Fail:', error);
    }
});
```

{% endcode %}

{% code title="Axios.js:" %}

```javascript
const axios = require('axios');

const url = 'https://api.cryptocloud.plus/v2/invoice/create';
const headers = {
    'Authorization': 'Token <API KEY>',
    'Content-Type': 'application/json'
};
const data = {
    amount: 100,
    shop_id: 'xBAivfPIbskwuEWj',
    currency: 'USD'
};

axios.post(url, data, { headers })
    .then(response => {
        console.log('Success:', response.data);
    })
    .catch(error => {
        console.error('Fail:', error);
    });
```

{% endcode %}
{% endtab %}

{% tab title="PHP" %}
{% code title="cURL:" %}

```php
<?php
$url = "https://api.cryptocloud.plus/v2/invoice/create";
$headers = array(
    "Authorization: Token <API KEY>",
    "Content-Type: application/json"
);

$data = array(
    "amount" => 100,
    "shop_id" => "xBAivfPIbskwuEWj",
    "currency" => "USD"
);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);

if($http_code == 200){
    echo "Success: " . $response;
} else {
    echo "Fail: " . $http_code . " " . $response;
}

curl_close($ch);
?>
```

{% endcode %}

{% code title="File\_get\_contents:" %}

```php
<?php
$url = "https://api.cryptocloud.plus/v2/invoice/create";
$headers = array(
    "http" => array(
        "header" => "Authorization: Token <API KEY>\r\n" .
                    "Content-Type: application/json\r\n",
        "method" => "POST",
        "content" => json_encode(array(
            "amount" => 100,
            "shop_id" => "xBAivfPIbskwuEWj",
            "currency" => "USD"
        )),
    ),
);

$context  = stream_context_create($headers);
$response = file_get_contents($url, false, $context);
$http_code = $http_response_header[0];

if(strpos($http_code, "200")){
    echo "Success: " . $response;
} else {
    echo "Fail: " . $http_code . " " . $response;
}
?>
```

{% endcode %}
{% endtab %}
{% endtabs %}

### Response examples

A successful request returns a response with the status `success` and a `result` object.

{% tabs %}
{% tab title="200: OK – Invoice has been created" %}

```json
{
    "status": "success",
    "result": {
        "uuid": "INV-89UX09KA",
        "created": "2026-01-27 09:03:58.958133",
        "address": "0xb07427fc721C23674c48233ffE93D3846ee58B63",
        "expiry_date": "2026-01-28 09:03:57.493361",
        "side_commission": "client",
        "side_commission_service": "merchant",
        "type_payments": "crypto",
        "amount": 0.034187,
        "amount_usd": 100.0,
        "amount_in_fiat": 100.0,
        "fee": 1.499999996212864e-06,
        "fee_usd": 0.0,
        "service_fee": 0.00065,
        "service_fee_usd": 1.9,
        "fiat_currency": "USD",
        "status": "created",
        "is_email_required": false,
        "link": "https://pay.cryptocloud.plus/89UX09KA",
        "invoice_id": null,
        "currency": {
            "id": 3,
            "code": "ETH",
            "fullcode": "ETH",
            "network": {
                "code": "ERC20",
                "id": 3,
                "icon": "https://cdn.cryptocloud.plus/img/network/ERC.svg",
                "fullname": "Ethereum"
            },
            "name": "Ethereum",
            "is_email_required": false,
            "stablecoin": false,
            "icon_base": "https://cdn.cryptocloud.plus/img/currency/ETH.svg",
            "icon_network": "https://cdn.cryptocloud.plus/img/currency/ETH.svg",
            "icon_qr": "https://cdn.cryptocloud.plus/img/stroke/ETH_STROKE.svg",
            "order": 9
        },
        "project": {
            "id": 1,
            "name": "Test",
            "fail": "https://test.com/failed-payment",
            "success": "https://test.com/successful-payment",
            "logo": "https://static.cryptocloud.plus/logo/L52hWwjt98uYtUF91765782359.174416.jpg"
        },
        "test_mode": false
    }
}
```

{% endtab %}
{% endtabs %}

### Response parameters

The `result` object contains:

<table data-full-width="false"><thead><tr><th>Name</th><th>Type</th><th width="198.35498046875">Example</th><th>Description</th></tr></thead><tbody><tr><td>uuid</td><td>string</td><td>INV-89UX09KA</td><td>Unique invoice identifier with the INV prefix</td></tr><tr><td>created</td><td>string</td><td>2026-01-01 12:00:00.000000</td><td>Invoice creation time in UTC+0 format: YYYY-MM-DD HH:MI:SS.FFFFFF</td></tr><tr><td>address</td><td>string</td><td>0xb07427&#x3C;...>E93D3846ee58B63</td><td><p>Payment address</p><p></p><p>Will be prefilled only if a cryptocurrency for payment is selected.</p><p></p><p>To select the currency on behalf of the customer, specify a project-supported currency in <code>add_fields.cryptocurrency</code>.</p></td></tr><tr><td>expiry_date</td><td>string</td><td>2026-01-02 12:00:00.000000</td><td><p>Invoice expiration date in UTC+0 format: YYYY-MM-DD HH:MI:SS.FFFFFF.</p><p></p><p>After the expiration time, the invoice status will change to <code>canceled</code> if payment has not been received.</p></td></tr><tr><td>side_commission</td><td>string</td><td>client</td><td>Transfer fee payer</td></tr><tr><td>side_commission_cc</td><td>string</td><td>client</td><td>Service fee payer</td></tr><tr><td>amount</td><td>float</td><td>0.033366</td><td>Invoice amount in the selected cryptocurrency</td></tr><tr><td>amount_usd</td><td>float</td><td>100.0</td><td>Invoice amount in USD</td></tr><tr><td>amount_in_fiat</td><td>float</td><td>100.0</td><td>Invoice amount in the creation currency (depends on the <code>currency</code> parameter)</td></tr><tr><td>fee</td><td>float</td><td>4.500000159168849e-06</td><td>Invoice transfer fee</td></tr><tr><td>fee_usd</td><td>float</td><td>0.01</td><td>Invoice transfer fee in USD</td></tr><tr><td>service_fee</td><td>float</td><td>0.000634</td><td>Service fee</td></tr><tr><td>service_fee_usd</td><td>float</td><td>1.9</td><td>Service fee in USD</td></tr><tr><td>fiat_currency</td><td>string</td><td>USD</td><td>Fiat currency code in which the invoice was created</td></tr><tr><td>status</td><td>string</td><td>created</td><td><p>Invoice status</p><p></p><p>When a create-invoice request is sent, the status is always <code>created</code>.</p><p></p><p>Other possible statuses: <code>paid</code> (paid), <code>partial</code> (partially paid), <code>overpaid</code> (overpaid), and <code>canceled</code> (canceled).</p></td></tr><tr><td>is_email_required</td><td>bool</td><td>false</td><td>Parameter for requiring the payer’s email in the invoice</td></tr><tr><td>link</td><td>string</td><td>pay.cryptocloud.plus/89UX09KA</td><td>Link to the invoice page</td></tr><tr><td>currency</td><td>dict</td><td><p>"currency": {</p><p>            "id": 3,</p><p>            "code": "ETH",</p><p>            "fullcode": "ETH",</p><p>            "network": {</p><p>                "code": "ERC20",</p><p>                "id": 3,</p><p>                "icon": "https://cdn.cryptocloud.plus/img/network/ERC.svg",</p><p>                "fullname": "Ethereum"</p><p>            },</p><p>            "name": "Ethereum",</p><p>            "is_email_required": false,</p><p>            "stablecoin": false,</p><p>            "icon_base": "https://cdn.cryptocloud.plus/img/currency/ETH.svg",</p><p>            "icon_network": "https://cdn.cryptocloud.plus/img/currency/ETH.svg",</p><p>            "icon_qr": "https://cdn.cryptocloud.plus/img/stroke/ETH_STROKE.svg",</p><p>            "order": 9</p><p>        }</p></td><td><p>Object of the selected cryptocurrency in the invoice.</p><p></p><p>Also contains the <code>network</code> object — information about the selected currency network.</p></td></tr><tr><td>project</td><td>dict</td><td><p>"project": {</p><p>            "id": 0,</p><p>            "name": "MyShop",</p><p>            "fail": "https://test.com/failed-payment",</p><p>            "success": "https://test.com/successful-payment",</p><p>            "logo": "https://static.cryptocloud.plus/logo/logo.jpg"</p><p>        }v</p></td><td>Object containing project information</td></tr><tr><td>test_mode</td><td>bool</td><td>false</td><td>Test invoice sign</td></tr></tbody></table>