Invoices

An invoice is a single payment request. You create it with a USD amount and a network; recv converts the price to the on-chain payable_amount, assigns one of your payout wallets as the destination_address, and tracks the payment until it settles.

All endpoints below live under https://recv.money/v1 and require an API key.

Create an invoice

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

Request body

The invoice environment (test/live) is inherited from the API key — there is no mode field in the body.

Headers

Example (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" }
    ]
  }'

Example (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"])

Invoice object

A 201/200 response returns the invoice object:

{
  "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="
}

Field reference

Statuses

A read of an invoice whose window has elapsed while still awaiting_payment is reported as expired.

Get an invoice

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

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

Returns the invoice object above, or 404 if it does not belong to your workspace.

List invoices

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": [ /* invoices */ ], "total": 134, "page": 1, "page_size": 50 }

Cancel an invoice

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

Cancelling sets the invoice to expired. Only workspace-created merchant invoices can be cancelled; subscription/plan invoices cannot (400).

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

Simulating payments (test mode)

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

Marks a test invoice as paid and fires webhooks, without any on-chain transfer. Requires an test_ key and a test invoice; otherwise returns 403/400.

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

Idempotency

POST /v1/invoices accepts an Idempotency-Key header. recv stores the result against the key + request body hash:

• Same key, same body → returns the original stored response.
• Same key, different body → 409 Conflict.
• Same key, original still processing → 409 Conflict.

Use a stable key per logical order (e.g. your order ID) so network retries never create duplicate invoices.

Example (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"])