openapi: 3.0.3
info:
  title: Bezant Payments API
  version: "1.0"
  description: |
    Crypto payment gateway. Create payments, get notified by signed webhooks, hold balances or settle directly to your wallet.

    **Supported assets** (always read `GET /v1/assets`): per-payment addresses for **USDT** — `USDT` (Tron/TRC20), `ETH-USDT`
    (Ethereum/ERC20), `BNB-USDT` (BNB Smart Chain/BEP20); exchange-custodied (shared address, exact unique amount, 60-min expiry)
    for USDC (Solana), BTC, XRP, SOL, LTC, DOGE, GRAM (TON, memo required; added 2026-10-06), … **Change 2026-10-05:** native `TRX`, `ETH` and `BNB` moved from per-payment addresses to the
    exchange-custodied flow — same codes, but the customer must send exactly `amount_crypto` before `expires_at`.
    **Change 2026-10-06:** the network fee on Tron USDT deposits and withdrawals is 4 USD (was 1.50). Fees: see /docs/getting-started.
    Authenticate with `X-Bezant-Api-Key`. Send `Idempotency-Key` on POSTs you may retry. Amounts are decimal strings.
    Webhooks are signed: `X-Bezant-Signature = HMAC-SHA256(webhook_secret, "{X-Bezant-Timestamp}." + body)`.
    Webhook events (`{"event", "merchant_id", "created_at", "data"}`): payment.unconfirmed, payment.updated (data = Payment + credited[]),
    withdrawal.completed, withdrawal.failed, transfer.completed, order.completed, order.failed, reserve.low, deposit.received, deposit.unconfirmed
    (long-lasting addresses). OTC desk guide: /docs/otc.
servers:
  - url: https://api.bezant.cc
security: [{ ApiKey: [] }]
tags:
  - {name: Payments, description: "Incoming payments (one address per payment; exchange coins use a unique amount)"}
  - {name: Addresses, description: "Long-lasting deposit addresses: one per customer per on-chain asset, credited on every transfer (deposit.received)"}
  - {name: Withdrawals}
  - {name: Transfers, description: "Move your USDT between networks (USDT = Tron, ETH-USDT = Ethereum, BNB-USDT = BNB Smart Chain) 1:1, instantly; then withdraw on the destination chain"}
  - {name: Balances}
  - {name: Settlement, description: "Custodial vs direct-to-wallet per asset, and the yearly subscription"}
  - {name: Orders, description: "Buy-and-deliver: pay in USDT from your balance, Bezant buys the coin on the exchange and delivers it to an address"}
  - {name: Account}
paths:
  /v1/me:
    get: {tags: [Account], summary: Current merchant, responses: {"200": {description: OK, content: {application/json: {schema: {$ref: '#/components/schemas/MerchantEnvelope'}}}}}}
    patch:
      tags: [Account]
      summary: Update default webhook URL and USDT reserve minimum
      requestBody: {content: {application/json: {schema: {type: object, properties: {webhook_url: {type: string, nullable: true}, reserve_min_usdt: {type: string, nullable: true, description: "Alert threshold for your available USDT; null = platform default"}}}}}}
      responses: {"200": {description: OK}}
  /v1/assets:
    get: {tags: [Account], summary: Assets you can accept, responses: {"200": {description: OK, content: {application/json: {schema: {type: object, properties: {assets: {type: array, items: {$ref: '#/components/schemas/Asset'}}}}}}}}}
  /v1/balances:
    get: {tags: [Balances], summary: Available and held balance per asset, responses: {"200": {description: OK, content: {application/json: {schema: {type: object, properties: {balances: {type: array, items: {$ref: '#/components/schemas/Balance'}}}}}}}}}
  /v1/ledger:
    get:
      tags: [Balances]
      summary: Your ledger entries (newest first)
      parameters: [{name: asset, in: query, schema: {type: string}}, {name: limit, in: query, schema: {type: integer, default: 100, maximum: 1000}}]
      responses: {"200": {description: OK}}
  /v1/quote:
    get:
      tags: [Payments]
      summary: Price an amount before creating a payment or withdrawal
      description: Returns our current rate, the crypto/fiat equivalents and the fees that would apply. Not binding; the rate is fixed when the payment is created.
      parameters:
        - {name: asset, in: query, required: true, schema: {type: string}}
        - {name: amount, in: query, required: true, schema: {type: string}}
        - {name: currency, in: query, schema: {type: string}, description: "USD (default), USDT (spot price) or the asset code for a crypto-denominated amount"}
      responses:
        "200": {description: OK, content: {application/json: {schema: {type: object, properties: {quote: {$ref: "#/components/schemas/Quote"}}}}}}
  /v1/payments:
    post:
      tags: [Payments]
      summary: Create a payment
      parameters: [{$ref: "#/components/parameters/IdempotencyKey"}]
      requestBody: {required: true, content: {application/json: {schema: {$ref: "#/components/schemas/PaymentRequest"}}}}
      responses:
        "201": {description: Created, content: {application/json: {schema: {$ref: '#/components/schemas/PaymentEnvelope'}}}}
        "404": {description: Unsupported asset}
        "502": {description: Backend (gateway/exchange) error}
    get:
      tags: [Payments]
      summary: List payments
      parameters: [{name: external_id, in: query, schema: {type: string}}, {name: address_id, in: query, schema: {type: string}}, {name: limit, in: query, schema: {type: integer, default: 50, maximum: 500}}]
      responses: {"200": {description: OK}}
  /v1/payments/{id}:
    get: {tags: [Payments], summary: Get a payment, parameters: [{name: id, in: path, required: true, schema: {type: string}}], responses: {"200": {description: OK, content: {application/json: {schema: {$ref: '#/components/schemas/PaymentEnvelope'}}}}, '404': {description: Not found}}}
  /v1/withdrawals:
    post:
      tags: [Withdrawals]
      summary: Withdraw to an address
      description: Amount + fees are put on hold immediately; the hold settles when the payout confirms and is released if it fails.
      parameters: [{$ref: "#/components/parameters/IdempotencyKey"}]
      requestBody: {required: true, content: {application/json: {schema: {$ref: "#/components/schemas/WithdrawalRequest"}}}}
      responses:
        "201": {description: Submitted, content: {application/json: {schema: {$ref: '#/components/schemas/WithdrawalEnvelope'}}}}
        "402": {description: Insufficient balance}
        "409": {description: external_id already used}
        "502": {description: Payout rejected by the backend (hold released)}
    get: {tags: [Withdrawals], summary: List withdrawals, parameters: [{name: external_id, in: query, schema: {type: string}}], responses: {"200": {description: OK}}}
  /v1/withdrawals/{id}:
    get: {tags: [Withdrawals], summary: Get a withdrawal, parameters: [{name: id, in: path, required: true, schema: {type: string}}], responses: {"200": {description: OK, content: {application/json: {schema: {$ref: '#/components/schemas/WithdrawalEnvelope'}}}}}}
  /v1/transfers:
    post:
      tags: [Transfers]
      summary: Move USDT to another network
      description: >-
        Debits `amount` (+ fee, currently none) from your `from_asset` balance and credits `amount` to your `to_asset` balance
        at once. Only between the USDT assets (USDT, ETH-USDT, BNB-USDT). No on-chain movement happens for you; withdraw on the
        destination network afterwards with POST /v1/withdrawals (that chain's network fee applies). Webhook: transfer.completed.
      parameters: [{$ref: "#/components/parameters/IdempotencyKey"}]
      requestBody: {required: true, content: {application/json: {schema: {$ref: "#/components/schemas/TransferRequest"}}}}
      responses:
        "201": {description: Completed, content: {application/json: {schema: {$ref: '#/components/schemas/TransferEnvelope'}}}}
        "400": {description: Not a USDT-to-USDT pair, or same asset}
        "402": {description: Insufficient balance (nothing moved)}
        "409": {description: external_id already used}
    get: {tags: [Transfers], summary: List transfers, parameters: [{name: external_id, in: query, schema: {type: string}}], responses: {"200": {description: OK}}}
  /v1/transfers/{id}:
    get: {tags: [Transfers], summary: Get a transfer, parameters: [{name: id, in: path, required: true, schema: {type: string}}], responses: {"200": {description: OK, content: {application/json: {schema: {$ref: '#/components/schemas/TransferEnvelope'}}}}}}
  /v1/addresses:
    post:
      tags: [Addresses]
      summary: Create (or return) the permanent deposit address for a customer and asset
      description: "Idempotent per (customer_ref, asset) while ACTIVE. mode DEDICATED (on-chain USDT: own address, any amount credited) or UNIQUE_AMOUNT (exchange-custodied coins: the exchange's permanent shared address; create a payment with address_id before each transfer so its unique amount identifies the customer)."
      parameters: [{$ref: "#/components/parameters/IdempotencyKey"}]
      requestBody: {required: true, content: {application/json: {schema: {type: object, required: [asset, customer_ref], properties: {asset: {type: string, example: USDT}, customer_ref: {type: string, description: Your id for the user or purpose}, label: {type: string}, callback_url: {type: string}, metadata: {type: object}}}}}}
      responses:
        "201": {description: Address, content: {application/json: {schema: {type: object, properties: {address: {$ref: "#/components/schemas/DepositAddress"}}}}}}
        "400": {description: Exchange-custodied asset or missing customer_ref}
    get:
      tags: [Addresses]
      summary: List addresses
      parameters: [{name: customer_ref, in: query, schema: {type: string}}, {name: asset, in: query, schema: {type: string}}, {name: status, in: query, schema: {type: string, enum: [ACTIVE, DISABLED, ALL], default: ACTIVE}}]
      responses: {"200": {description: OK}}
  /v1/addresses/{id}:
    get: {tags: [Addresses], summary: Get an address, parameters: [{name: id, in: path, required: true, schema: {type: string}}], responses: {"200": {description: OK}, "404": {description: Not found}}}
    patch:
      tags: [Addresses]
      summary: Disable or relabel an address
      description: DISABLED hides it from lists and lets a new address be issued for the same customer; transfers that still arrive are credited anyway (an address cannot be un-watched).
      parameters: [{name: id, in: path, required: true, schema: {type: string}}]
      requestBody: {content: {application/json: {schema: {type: object, properties: {status: {type: string, enum: [ACTIVE, DISABLED]}, label: {type: string}, callback_url: {type: string}}}}}}
      responses: {"200": {description: OK}}
  /v1/addresses/{id}/deposits:
    get: {tags: [Addresses], summary: Transfers credited to this address (newest first), parameters: [{name: id, in: path, required: true, schema: {type: string}}], responses: {"200": {description: OK, content: {application/json: {schema: {type: object, properties: {deposits: {type: array, items: {$ref: "#/components/schemas/AddressDeposit"}}}}}}}}}
  /v1/orders/quote:
    get:
      tags: [Orders]
      summary: Cost of buying and delivering an amount of a coin
      parameters: [{name: asset, in: query, required: true, schema: {type: string}}, {name: amount, in: query, required: true, schema: {type: string}}]
      responses: {"200": {description: OK, content: {application/json: {schema: {type: object, properties: {quote: {$ref: "#/components/schemas/OrderQuote"}}}}}}, "400": {description: "Not an exchange coin, or amount below the exchange's minimum withdrawal (min_amount)"}, "503": {description: "Exchange unavailable, trading or withdrawals of the coin suspended (retry later)"}}
  /v1/orders:
    post:
      tags: [Orders]
      summary: Buy a coin on the exchange and deliver it to an address
      description: |
        Holds up to `hold` USDT from your balance, market-buys the coin (plus trading and withdrawal fees) on KuCoin spot, charges the real
        cost + Bezant fee, returns the unused hold, and withdraws exactly `amount` to `address`. Only exchange-custodied coins (BTC, XRP, SOL, …).
        `UNDELIVERED` means the coin was bought but the exchange withdrawal failed; an operator retries it — you are not charged twice.
      parameters: [{$ref: "#/components/parameters/IdempotencyKey"}]
      requestBody: {required: true, content: {application/json: {schema: {type: object, required: [asset, amount, address], properties: {asset: {type: string}, amount: {type: string, description: Coin amount the customer receives}, address: {type: string}, memo: {type: string}, external_id: {type: string}, callback_url: {type: string}}}}}}
      responses:
        "201": {description: Buying or delivering, content: {application/json: {schema: {$ref: "#/components/schemas/OrderEnvelope"}}}}
        "400": {description: "amount below the exchange's minimum withdrawal for the coin (see min_amount on the quote); nothing is bought or held"}
        "402": {description: Insufficient USDT balance}
        "409": {description: external_id already used}
        "502": {description: Purchase failed (hold released) or bought but undelivered}
        "503": {description: "Exchange unavailable, trading or withdrawals of the coin suspended; nothing is bought or held"}
    get: {tags: [Orders], summary: List orders, parameters: [{name: external_id, in: query, schema: {type: string}}], responses: {"200": {description: OK}}}
  /v1/orders/{id}:
    get: {tags: [Orders], summary: Get an order, parameters: [{name: id, in: path, required: true, schema: {type: string}}], responses: {"200": {description: OK, content: {application/json: {schema: {$ref: "#/components/schemas/OrderEnvelope"}}}}}}
  /v1/settlement-policies:
    get: {tags: [Settlement], summary: Policies per asset, responses: {"200": {description: OK, content: {application/json: {schema: {type: object, properties: {policies: {type: array, items: {$ref: '#/components/schemas/Policy'}}}}}}}}}
  /v1/settlement-policies/{asset}:
    put:
      tags: [Settlement]
      summary: Set mode, payout address and pooling threshold
      description: DIRECT needs an active subscription. Changing an existing address requires e-mail confirmation (or a 24 h hold when e-mail is not configured).
      parameters: [{name: asset, in: path, required: true, schema: {type: string}}]
      requestBody: {content: {application/json: {schema: {type: object, properties: {mode: {type: string, enum: [CUSTODIAL, DIRECT]}, address: {type: string}, threshold: {type: string}}}}}}
      responses: {"200": {description: OK, content: {application/json: {schema: {type: object, properties: {policy: {$ref: '#/components/schemas/Policy'}}}}}}, '402': {description: Subscription required}}
  /v1/subscriptions:
    post:
      tags: [Settlement]
      summary: Buy or renew direct-to-wallet for an asset (50 USDT / year, charged from your USDT balance)
      parameters: [{$ref: "#/components/parameters/IdempotencyKey"}]
      requestBody: {required: true, content: {application/json: {schema: {type: object, required: [asset], properties: {asset: {type: string}}}}}}
      responses: {"201": {description: Active}, '402': {description: Insufficient USDT balance}}
    get: {tags: [Settlement], summary: List subscriptions, responses: {"200": {description: OK}}}
components:
  securitySchemes:
    ApiKey: {type: apiKey, in: header, name: X-Bezant-Api-Key}
  parameters:
    IdempotencyKey: {name: Idempotency-Key, in: header, required: false, schema: {type: string}, description: "Same key + same merchant replays the original response"}
  schemas:
    Asset: {type: object, properties: {code: {type: string, example: USDT}, name: {type: string}, decimals: {type: integer}, backend: {type: string, enum: [shkeeper, exchange]}}}
    Balance: {type: object, properties: {asset: {type: string}, available: {type: string}, held: {type: string}}}
    PaymentRequest:
      type: object
      required: [asset, amount, external_id]
      properties:
        asset: {type: string, example: USDT, description: "An enabled asset code from GET /v1/assets (USDT, ETH-USDT, BNB-USDT, ETH, TRX, BNB, BTC, …)"}
        amount: {type: string, example: "25"}
        currency: {type: string, default: USD, description: "USD; USDT to price at the exchange spot rate; or the asset code to request an exact crypto amount (e.g. currency=ETH-USDT, amount=100)"}
        external_id: {type: string, description: Your order id}
        callback_url: {type: string, format: uri}
        metadata: {type: object}
        credit_asset: {type: string, description: "Top-ups: USDT to credit the net amount to your USDT working balance when paying on another network (ETH-USDT, BNB-USDT)"}
        topup: {type: boolean, description: "Mark as a top-up of your own balance: no Bezant fee (the network fee still applies). Implied by credit_asset."}
        address_id: {type: string, description: "Attach this payment to a long-lasting address (required to identify a customer on exchange-custodied coins); the address's asset must match"}
    Payment:
      type: object
      properties:
        id: {type: string, example: pay_…}
        external_id: {type: string}
        asset: {type: string}
        address: {type: string}
        memo: {type: string, nullable: true, description: Destination tag for XRP-style coins}
        expires_at: {type: integer, nullable: true, description: Unique-amount reservation expiry (exchange coins)}
        currency: {type: string}
        amount: {type: string, description: "Requested, in currency"}
        amount_crypto: {type: string, description: "What the customer must send (merchant amount + network fee for on-chain assets)"}
        network_fee_crypto: {type: string, description: "Sweep cost the customer pays on top (0 for exchange coins)"}
        amount_crypto_net: {type: string, description: "amount_crypto minus the network fee = the merchant's amount in crypto"}
        exchange_rate: {type: string, nullable: true}
        status: {type: string, enum: [PENDING, PARTIAL, PAID, OVERPAID]}
        paid: {type: boolean}
        received_crypto: {type: string}
        fee_crypto: {type: string}
        net_crypto: {type: string}
        created_at: {type: integer}
    Quote:
      type: object
      properties:
        asset: {type: string}
        currency: {type: string}
        amount: {type: string}
        rate: {type: string, description: USD per 1 unit of the asset}
        rate_currency: {type: string}
        amount_crypto: {type: string}
        amount_fiat: {type: string}
        deposit: {type: object, properties: {fee_crypto: {type: string}, network_fee_crypto: {type: string}, amount_to_pay_crypto: {type: string}, net_crypto: {type: string}, direct_mode: {type: boolean}}}
        withdrawal: {type: object, properties: {fee_bezant: {type: string}, fee_network: {type: string}, total_crypto: {type: string}}}
    DepositAddress:
      type: object
      properties:
        id: {type: string, example: addr_…}
        asset: {type: string}
        address: {type: string}
        memo: {type: string, nullable: true}
        mode: {type: string, enum: [DEDICATED, UNIQUE_AMOUNT]}
        customer_ref: {type: string}
        label: {type: string, nullable: true}
        status: {type: string, enum: [ACTIVE, DISABLED]}
        metadata: {type: object, nullable: true}
        total_received: {type: string, description: "Sum of transfers credited (dedicated) or of payments made against it (unique amount)"}
        total_net: {type: string}
        deposits_count: {type: integer}
        last_deposit_at: {type: integer, nullable: true}
        created_at: {type: integer}
    AddressDeposit:
      type: object
      properties: {txid: {type: string}, amount_crypto: {type: string}, amount_fiat: {type: string}, network_fee_crypto: {type: string}, fee_crypto: {type: string}, net_crypto: {type: string}, credited_at: {type: integer}}
    OrderQuote:
      type: object
      properties: {asset: {type: string}, amount: {type: string}, min_amount: {type: string, description: "Smallest amount the exchange will withdraw for this coin; smaller orders are refused (400) before anything is bought"}, pay_asset: {type: string}, price: {type: string, description: Exchange ask in USDT}, trade_size: {type: string}, fee_network: {type: string}, estimated_cost: {type: string}, fee_percent: {type: string}, hold: {type: string, description: USDT held until the fill is known}}
    Order:
      type: object
      properties:
        id: {type: string}
        external_id: {type: string, nullable: true}
        asset: {type: string}
        amount: {type: string}
        address: {type: string}
        memo: {type: string, nullable: true}
        pay_asset: {type: string}
        price: {type: string}
        trade_size: {type: string}
        hold: {type: string}
        cost: {type: string, nullable: true, description: USDT actually spent on the exchange}
        fee_bezant: {type: string, nullable: true}
        charged: {type: string, nullable: true, description: cost + fee_bezant}
        fee_network: {type: string}
        status: {type: string, enum: [PENDING, BUYING, DELIVERING, COMPLETED, FAILED, UNDELIVERED]}
        txid: {type: string, nullable: true}
        error: {type: string, nullable: true}
    OrderEnvelope: {type: object, properties: {status: {type: string}, order: {$ref: "#/components/schemas/Order"}}}
    PaymentEnvelope: {type: object, properties: {status: {type: string}, payment: {$ref: "#/components/schemas/Payment"}}}
    WithdrawalRequest:
      type: object
      required: [asset, amount, address]
      properties: {asset: {type: string}, amount: {type: string}, address: {type: string}, memo: {type: string}, external_id: {type: string}, callback_url: {type: string}}
    Withdrawal:
      type: object
      properties:
        id: {type: string}
        external_id: {type: string, nullable: true}
        asset: {type: string}
        address: {type: string}
        memo: {type: string, nullable: true}
        kind: {type: string, enum: [MANUAL, SETTLEMENT]}
        source: {type: string, enum: [GATEWAY, EXCHANGE, EXCHANGE_FALLBACK], description: "Where it was paid from; EXCHANGE_FALLBACK = KuCoin covered a hot-wallet shortfall (same result for you)"}
        amount: {type: string}
        fee_bezant: {type: string}
        fee_network: {type: string}
        total: {type: string, description: "amount + fees, held from your balance"}
        status: {type: string, enum: [PENDING, SUBMITTED, COMPLETED, FAILED]}
        txid: {type: string, nullable: true}
        error: {type: string, nullable: true}
    WithdrawalEnvelope: {type: object, properties: {status: {type: string}, withdrawal: {$ref: "#/components/schemas/Withdrawal"}}}
    TransferRequest:
      type: object
      required: [from_asset, to_asset, amount]
      properties:
        from_asset: {type: string, enum: [USDT, ETH-USDT, BNB-USDT]}
        to_asset: {type: string, enum: [USDT, ETH-USDT, BNB-USDT]}
        amount: {type: string, description: "USDT credited to to_asset"}
        external_id: {type: string}
    Transfer:
      type: object
      properties:
        id: {type: string}
        external_id: {type: string, nullable: true}
        from_asset: {type: string}
        to_asset: {type: string}
        amount: {type: string}
        fee: {type: string, description: "Bezant fee in from_asset (0 today)"}
        total: {type: string, description: "amount + fee, debited from from_asset"}
        status: {type: string, enum: [COMPLETED]}
        created_at: {type: integer}
    TransferEnvelope: {type: object, properties: {status: {type: string}, transfer: {$ref: "#/components/schemas/Transfer"}}}
    Policy:
      type: object
      properties:
        asset: {type: string}
        mode: {type: string, enum: [CUSTODIAL, DIRECT]}
        active: {type: boolean, description: DIRECT with a live subscription and an address}
        address: {type: string, nullable: true}
        pending_address: {type: string, nullable: true}
        pending_effective_at: {type: integer, nullable: true}
        threshold: {type: string}
        subscription_expires_at: {type: integer, nullable: true}
    MerchantEnvelope: {type: object, properties: {merchant: {type: object, properties: {id: {type: string}, name: {type: string}, email: {type: string}, webhook_url: {type: string, nullable: true}, reserve: {type: object, properties: {asset: {type: string}, available: {type: string}, minimum: {type: string, nullable: true}, minimum_source: {type: string, nullable: true, enum: [merchant, default]}, low: {type: boolean}}}}}}}
