Bitcofy API documentation

Detailed guide for project creation, invoice issuing, webhook/IPN processing, direct payouts and payout request flow.

Quick start

1. Create an owner cabinet account and obtain a project API key.
2. Create a project and configure invoice language, webhook and enabled assets.
3. Create an invoice via `/api/v1/invoices` and give the client the `/payment_{invoice_hash}` link.
4. On the merchant side, treat the order as successful only after the `paid` status.
5. For payouts use either a direct signed payout or a payout request with owner approval.

Main flows

• Invoices: create, get public link, poll status, choose payment option.
• Cabinet: registration, login, projects, API keys, webhook config, security, 2FA.
• Withdraw: direct payout or payout request approved by the project owner.
• Admin: global billing/gas policy, network monitoring, sweep and processing queues.

Create invoice

{
  "project_id": "project_xxx",
  "order_id": "order_1001",
  "amount_fiat": "100.00",
  "fiat_currency": "USD",
  "buy_type": "package",
  "language": "auto"
}

Invoice response example

{
  "invoice_id": "inv_xxx",
  "invoice_hash": "9c8f...",
  "invoice_url": "https://pay.bitcofy.pro/payment_9c8f...",
  "status": "created",
  "resolved_language": "ru",
  "payment_options": [
    {
      "network": "Tron",
      "asset": "USDT",
      "amount_crypto": "100.12",
      "required_confirmations": 1
    }
  ]
}

Create payout request

{
  "network": "Tron",
  "asset": "USDT",
  "amount": "50.00",
  "destination_address": "T...",
  "idempotency_key": "withdraw_001",
  "note": "manual withdrawal"
}

Payout request response example

{
  "request_id": "par_xxx",
  "status": "requested",
  "network": "Tron",
  "asset": "USDT",
  "amount": "50.00",
  "destination_address": "T..."
}

Webhook / IPN

• Webhook is configured per project from the cabinet.
• Merchant processing must be idempotent.
• For business logic, rely on the final invoice status and aggregated API amounts.
• The Tron energy rental callback uses the `/rent-callback` endpoint.

Important notes

• Direct payouts require Ed25519 signing.
• Tron activation and gas preparation are handled only in backend logic.
• For `package` a full exact payment is required, while for `balance` the credited amount is the actual payment minus fee.
• If reserve or aggregated balance is insufficient, payout API returns `409` with the available limit.
• Project wallet seed files are created automatically when deposit addresses are allocated.