# Create invoice


The method lets you **create an invoice** (payment bill) and get a link to the payment form. Send the request to the `init_invoice` endpoint. After payment or invoice expiry, the final status is sent to `invoice_notify_url` configured in project settings.

Request format and signature — in [API request format](./init-request.md).

## How it works

1. **Request** — your server sends a signed request to `init_invoice` with amount and `invoice_user_data`.
2. **Response** — the API returns `invoice_id` and payment page `url`.
3. **Payment** — redirect the payer to `url` or share the link another way.
4. **Notification (callback)** — on final invoice status, **POST** JSON is sent to the project `invoice_notify_url`.

`status` code meanings — in [Transaction statuses](./transaction-statuses.md).

## Technical details

| | |
| --- | --- |
| **Endpoint** | `https://api.1payment.com/init_invoice` |
| **Methods** | `GET`, `POST` |
| **Response format** | JSON |

## Request parameters

### Required

| Parameter | Type | Description |
| --- | --- | --- |
| `partner_id` | Integer | Your unique ID in the 1Payment system. |
| `project_id` | Integer | Your project identifier. |
| `amount` | Number | Invoice amount in project currency (e.g. `50`). |
| `invoice_user_data` | String | Your internal invoice ID (unique on the partner side). |
| `sign` | String | Request signature (see "Signature" section). |

### Optional

| Parameter | Type | Description |
| --- | --- | --- |
| `description` | String | Payment description for the payer. |
| `success_url` | String | Payer return URL after successful payment. |
| `failure_url` | String | Payer return URL after payment error. |

## Signature generation (`sign`)

Signature: MD5, lowercase (hex). General rules — [API request format](./init-request.md#request-signature-sign).

**Formula:**

```text
MD5(init_invoice + <parameters_without_sign_in_alphabetical_order_joined_by_&> + <API_KEY>)
```

**Example string before hashing** (as in archived documentation, minimal example without `invoice_user_data`):

```text
init_invoiceamount=50&description=test_payment&partner_id=1234&project_id=5678secret_key
```

If you send `invoice_user_data`, `success_url`, and other fields, they are included in the signature string in alphabetical order.

### Signature verification in the documentation

{% signatureVerifier method="init_invoice" preset="init_invoice" /%}

## Request examples

{% codeTabs %}
{% tab label="Node.js" %}

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

async function createInvoice(apiKey, params) {
  // 1. Сортируем параметры по алфавиту
  const sortedKeys = Object.keys(params).sort();
  const queryString = sortedKeys.map((key) => `${key}=${params[key]}`).join('&');

  // 2. Подпись с префиксом init_invoice
  const baseString = `init_invoice${queryString}${apiKey}`;
  params.sign = crypto.createHash('md5').update(baseString).digest('hex');

  // 3. GET-запрос
  const response = await axios.get('https://api.1payment.com/init_invoice', { params });
  return response.data;
}

const apiKey = process.env.ONEPAYMENT_API_KEY;
const data = {
  partner_id: 1234,
  project_id: 5678,
  amount: 50,
  description: 'test_payment',
  invoice_user_data: 'inv_12345',
};

createInvoice(apiKey, data).then(console.log);
```

{% /tab %}
{% tab label="Python" %}

```python
import hashlib
import os
import requests

def create_invoice(api_key: str, params: dict) -> dict:
    # 1. Сортировка параметров по алфавиту
    sorted_keys = sorted(params.keys())
    query_string = "&".join(f"{k}={params[k]}" for k in sorted_keys)

    # 2. Подпись init_invoice
    base_string = f"init_invoice{query_string}{api_key}"
    params["sign"] = hashlib.md5(base_string.encode("utf-8")).hexdigest()

    # 3. GET-запрос
    response = requests.get("https://api.1payment.com/init_invoice", params=params)
    response.raise_for_status()
    return response.json()

api_key = os.environ["ONEPAYMENT_API_KEY"]
data = {
    "partner_id": 1234,
    "project_id": 5678,
    "amount": 50,
    "description": "test_payment",
    "invoice_user_data": "inv_12345",
}
print(create_invoice(api_key, data))
```

{% /tab %}
{% tab label="PHP" %}

```php
<?php

function createInvoice(string $apiKey, array $params): string
{
    // 1. Сортировка параметров по алфавиту
    ksort($params, SORT_LOCALE_STRING);
    $tail = '';
    foreach ($params as $k => $v) {
        if ($k === 'sign') {
            continue;
        }
        $tail .= "{$k}={$v}&";
    }
    $tail = substr($tail, 0, -1);

    // 2. Формирование подписи (префикс init_invoice)
    $params['sign'] = md5('init_invoice' . $tail . $apiKey);

    // 3. Запрос к API
    $url = 'https://api.1payment.com/init_invoice?' . http_build_query($params);
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    $response = curl_exec($ch);
    curl_close($ch);

    return $response;
}

// Пример данных запроса
$apiKey = getenv('ONEPAYMENT_API_KEY');
$data = [
    'partner_id' => 1234,
    'project_id' => 5678,
    'amount' => 50,
    'description' => 'test_payment',
    'invoice_user_data' => 'inv_12345',
];

echo createInvoice($apiKey, $data);
```

{% /tab %}
{% tab label="cURL" %}

```bash
# 1–2. Подпись: md5("init_invoice" + amount=50&description=test_payment&invoice_user_data=inv_12345&partner_id=1234&project_id=5678 + API_KEY)

curl -sS "https://api.1payment.com/init_invoice?partner_id=1234&project_id=5678&amount=50&description=test_payment&invoice_user_data=inv_12345&sign=PASTE_MD5_HEX"
```

{% /tab %}
{% /codeTabs %}

## API response

Successful response (`200`):

```json
{
  "invoice_id": "inv_dp2eqgnyt008ocg88wwsw00oksgs8s88",
  "url": "https://merchant.1payment.com/xZ5g7F"
}
```

| Field | Description |
| --- | --- |
| `invoice_id` | Invoice ID in the 1Payment system. |
| `url` | Payment form link; redirect the payer to this URL. |

Request error (`400`):

```json
{
  "error_code": 2
}
```

## Status notifications (callbacks)

After the invoice reaches a **final** status, a **POST** JSON notification is sent to your `invoice_notify_url` (from project settings).

| Parameter | Type | Req. | Description |
| --- | --- | --- | --- |
| `type` | String | Yes | Notification type; for invoices — `invoice`. |
| `invoice_id` | String | Yes | Invoice ID in the 1Payment system. |
| `order_id` | String | No | On successful payment — transaction ID that paid the invoice. |
| `project_id` | Integer | Yes | Your project ID. |
| `status` | Integer | Yes | `3` — invoice paid, `4` — payment waiting period expired. |
| `init_time` | String | Yes | Invoice creation time. |
| `vaild_till` | String | Yes | Invoice expiry time (field name as in API). |
| `amount` | Number | Yes | Invoice amount. |
| `currency` | String | Yes | Invoice currency (ISO 4217). |
| `invoice_user_data` | String | Yes | Invoice ID sent at creation. |
| `sign` | String | Yes | Callback signature. |

**Important:** your server must return **HTTP 200 OK**. Otherwise the system retries the callback **once per minute for 10 minutes**.

**Callback signature verification:** MD5 of all parameters in alphabetical order joined by `&` + `API_KEY` (**without** the `init_invoice` prefix). Details — in [API request format](./init-request.md#callbacks-notifications).

## Related sections

- [API request format](./init-request.md)
- [Transaction statuses](./transaction-statuses.md)
- [Error codes (API)](./error-codes-api.md)
- [Error codes (declines)](./decline-error-codes.md)