Инвойсы

Инвойс — это один запрос на оплату. Вы создаете его с суммой в долларах и сетью; recv пересчитывает цену в сумму к оплате on-chain payable_amount, назначает один из ваших кошельков как destination_address и отслеживает платеж до его завершения.

Все endpoint'ы ниже находятся под https://recv.money/v1 и требуют API-ключ.

Создание счета

POST /v1/invoices        (scope: invoices:write)

Тело запроса

Окружение счета (test/live) наследуется от API-ключа — в теле нет поля mode.

Заголовки

Пример (curl)

curl -X POST https://recv.money/v1/invoices \
  -H "X-API-Key: $RECV_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-9841" \
  -d '{
    "title": "Premium Subscription",
    "base_amount_usd": "100.00",
    "payment_options": [
      { "network": "TRON", "asset": "USDT" },
      { "network": "SOLANA", "asset": "SOL" }
    ]
  }'

Пример (Python)

import requests

resp = requests.post(
    "https://recv.money/v1/invoices",
    headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
    json={
        "title": "Premium Subscription",
        "base_amount_usd": "100.00",
        "payment_options": [
            {"network": "TRON", "asset": "USDT"},
            {"network": "SOLANA", "asset": "SOL"},
        ],
    },
)
invoice = resp.json()
print("Checkout:", "https://recv.money" + invoice["checkout_url"])

Объект инвойса

Ответ 201/200 возвращает объект счета:

{
  "id": 482,
  "public_id": "pub_abcdef123",
  "title": "Premium Subscription",
  "kind": "merchant",
  "subscription_days": 0,
  "plan_code": "developer",
  "checkout_badge": "Merchant Checkout",
  "base_amount_usd": "100.00",
  "payable_amount": "100.000000",
  "payable_network": "TRON",
  "payable_asset": "USDT",
  "payment_options": [
    {
      "network": "TRON",
      "asset": "USDT",
      "payable_amount": "100.000123",
      "destination_address": "TQDt...",
      "payment_comment": "",
      "payment_uri": "TQDt...",
      "is_default": true
    },
    {
      "network": "SOLANA",
      "asset": "SOL",
      "payable_amount": "0.684211",
      "destination_address": "9x...",
      "payment_comment": "",
      "payment_uri": "9x...",
      "is_default": false
    }
  ],
  "destination_address": "EQC...",
  "payment_comment": "",
  "status": "awaiting_payment",
  "environment": "live",
  "mode": "live",
  "expires_at": "2026-05-31T22:00:00Z",
  "created_at": "2026-05-31T21:00:00Z",
  "tx_hash": null,
  "received_amount": "0.000000",
  "review_reason": null,
  "finalized_at": null,
  "checkout_url": "/app/checkout/pub_abcdef123",
  "payment_uri": "ton://transfer/EQC...?amount=100000000000&text="
}

Справочник полей

Статусы

Чтение счета, окно которого истекло, пока он еще awaiting_payment, возвращается как expired.

Получение счета

GET /v1/invoices/:id     (scope: invoices:read)

curl https://recv.money/v1/invoices/482 -H "X-API-Key: $RECV_API_KEY"

Возвращает объект счета выше или 404, если он не принадлежит вашему workspace.

Список счетов

GET /v1/invoices         (scope: invoices:read)

curl "https://recv.money/v1/invoices?page=1&page_size=50" \
  -H "X-API-Key: $RECV_API_KEY"

{ "items": [ /* счета */ ], "total": 134, "page": 1, "page_size": 50 }

Отмена счета

POST /v1/invoices/:id/cancel     (scope: invoices:write)

Отмена переводит счет в expired. Отменять можно только merchant-счета, созданные в workspace; подписочные/тарифные счета отменить нельзя (400).

curl -X POST https://recv.money/v1/invoices/482/cancel \
  -H "X-API-Key: $RECV_API_KEY"

Симуляция платежей (test mode)

POST /v1/test/invoices/:id/simulate-payment     (scope: invoices:write)

Помечает тестовый счет как paid и отправляет вебхуки без перевода on-chain. Требует ключ test_ и тестовый счет; иначе возвращает 403/400.

curl -X POST https://recv.money/v1/test/invoices/482/simulate-payment \
  -H "X-API-Key: $RECV_API_KEY"

Идемпотентность

POST /v1/invoices принимает заголовок Idempotency-Key. recv сохраняет результат по ключу + хешу тела запроса:

• Тот же ключ, то же тело → возвращает исходный сохраненный ответ.
• Тот же ключ, другое тело → 409 Conflict.
• Тот же ключ, исходный запрос еще обрабатывается → 409 Conflict.

Используйте стабильный ключ на логический заказ (например, ваш order ID), чтобы повторы сети не создавали дубликаты счетов.

Пример (Go)

req, _ := http.NewRequest("GET", "https://recv.money/v1/invoices/"+id, nil)
req.Header.Set("X-API-Key", apiKey)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var invoice map[string]any
json.NewDecoder(resp.Body).Decode(&invoice)
fmt.Println("Status:", invoice["status"])