DOCSEARCHbyAlgolia
Submit Docs

UtcPay Documentation

website·Indexed 31 days ago

https://doc.utcpay.com

A non-custodial Web3 digital asset payment protocol providing a decentralized smart contract gateway for cryptocurrencies. Documentation covers merchant onboarding, API integration for payments, recharges, and subscriptions, as well as the Signer tool (v1.4.0) for offline signatures of withdrawal transactions on EVM and TVM chains.

Tokens
46.6K
Snippets
123
Records
357
Agent score
50%

What's inside UtcPay

  1. Overview of UtcPay non-custodial payment protocol

    UtcPay is a non-custodial, decentralized digital asset payment protocol that allows Web2 companies to integrate Web3 payment channels without changing core business logic. It uses smart contracts and multi-signature technology to ensure that merchant funds are not stored on the platform but in customized smart contracts, giving merchants full control over their assets. The platform provides payment collection and deposit/withdrawal services, ensuring all transactions are confirmed on-chain.

  2. Overview of UtcPay Subscription Flow

    UtcPay allows merchants to create subscription plans in the admin console and then generate dedicated subscription links for users via API. Users authorize the subscription through their wallets. The merchant then uses the Signer service to initiate charges at intervals defined by the plan, with callbacks triggered for each event.

    Integration Flow:

    1. Create subscription plan in Admin Console.
    2. Call createSubscribeOrder API to generate a subscription link.
    3. Redirect user to the subscription page for signing and authorization.
    4. Periodically query chargeable subscriptions and trigger Signer billing.
    5. Handle subscription callbacks.

  3. Overview of UTCPay Cross-Chain Swap capabilities

    The UTCPay Admin Console includes a built-in cross-chain swap tool that allows users to transfer assets between major blockchains without external bridge integration. It supports USDT and other mainstream stablecoins and native coins across TRON (TRC20), Ethereum (ERC20), and BSC (BEP20). Funds are sourced from the Hot Wallet (Finance) account, and fees are integrated into the real-time swap rate. Settlement typically occurs within minutes, depending on network congestion.

  4. Manage merchant payments via the UTCPay admin console

    Merchants who do not wish to use API integration can manage their payment operations directly through the UTCPay admin console. The console provides tools for generating recharge addresses, setting up prepaid deposits, enabling KYT (Know Your Transaction) detection, and configuring fund movement strategies such as auto-sweep and auto-withdrawal, as well as handling blacklisted fund sweeps.

  5. Understand Tag Address allocation and management

    Tag Address allows merchants to categorize wallet addresses into pools. When a payment order is created with a specific tagId, the system assigns a receiving address based on these rules:

    1. If an available address exists under the specified tag, the system prioritizes reusing it.
    2. If all addresses under the tag are occupied, the system automatically creates a new address and assigns it to that tag.

    This mechanism enables address categorization, reuse, and automatic expansion for merchants managing large volumes of receiving addresses.

  6. Deploy and use the Signer service

    The Signer is a merchant-deployed service responsible for securely managing private keys and signing on-chain transactions. It is a critical dependency for the automatic billing flow to function, as it performs the sign-and-broadcast operation for subscription charges.

  7. Query transaction information using a transaction hash

    Use the GET /transaction/info endpoint to retrieve detailed information about a specific transaction on the chain. You must provide the transaction hash to identify the record. The API returns a 200 OK response upon successful retrieval, or error codes such as 401 (Unauthorized), 403 (Forbidden), or 404 (Not Found) if the request fails or the transaction is not found.
    GET /transaction/info?hash={transaction_hash}

  8. Manage wallet addresses using Tag Address

    Tag Address allows merchants to categorize and manage wallet addresses by assigning them to specific tags. When creating a payment order, specifying a tagId triggers the system to automatically assign a receiving address from the associated tagged address pool based on the following allocation rules:

    1. Reuse: If an available address exists under the specified tag, the system prioritizes reusing it.
    2. Automatic Creation: If all addresses under the tag are currently occupied, the system automatically creates a new address.
    3. Automatic Assignment: Any newly created address is automatically assigned to the same tag.

    This mechanism is designed for scenarios requiring address categorization, reuse, and automatic expansion when managing a large volume of receiving addresses.

  9. Understand the UTCPay Self-Custody Model

    UTCPay utilizes a self-custody model based on a hierarchy of sub-contracts, hot contracts, and cold contracts. This architecture ensures that merchants maintain full control over their assets, preventing the service provider from accessing merchant funds.

  10. Ensure data privacy via nested contracts

    UTCPay implements a transfer method using multi-layer nested contracts. This structure makes it difficult for scripts to trace transactions, providing strong privacy for merchant data.

  11. Implement a Secure Self-Custody architecture

    To achieve secure self-custody, the system must be built upon these four key elements:

    1. Smart Contract Management: All crypto asset operations must be managed by smart contracts, with permissions held exclusively by the project team.
    2. System-Level Multi-Signature: Implement a multi-signature system at the system level to avoid the inconvenience and risk of frequent direct interactions with cold contracts.
    3. Permission Isolation: Establish strict fund flow rules:
      • Funds in sub-contracts can only be transferred to cold contracts.
      • Assets in cold contracts can only be accessed via multi-signature operations by super administrators.
    4. Monitoring and Updates: Integrate automated security updates, detection scripts, and alert modules to address emerging threats.

  12. Understand Secure Self-Custody principles

    Secure self-custody is a smart contract-based approach to managing crypto assets that removes reliance on third-party servers and prevents single points of failure. A solution qualifies as secure self-custody if it meets two criteria:

    1. Merchant Ownership: All services and nodes must be fully owned by the merchant with ultimate authority.
    2. Fault Tolerance: The loss of any single node or server authority must not result in financial loss. This is achieved by separating the Service Module (Web2 servers) from the Asset Custody Module (smart contracts). Even if all server authorities are compromised, assets remain recoverable via multi-signature permissions held by senior administrators.