CryptPays

Core concepts

Understand the payment contract

Learn how CryptPays identifies assets and payment addresses, applies minimums and finality, selects transaction priority, and reports payment accounting.

Merchant-facing concepts Live values come from the API

Asset identity

Tickers and Asset Discovery

Merchant endpoints use canonical tickers in the form {network_standard}_{asset}. Use the ticker returned by GET /api/cryptocurrencies rather than deriving or hardcoding one.

Representative canonical ticker forms
FamilyNative exampleToken example
Ethereumerc20_etherc20_usdt
BNB Smart Chainbep20_bnbbep20_usdt
Bitcoinbitcoin_btc—
Litecoinlitecoin_ltc—
Solanasol_solsol_usdc
TRONtrc20_trxUse the live catalog

Some input aliases are accepted for compatibility, but public discovery and info responses return the canonical ticker. Examples above describe identifier formats, not current asset availability.

Address identity

Address Families and Callback Reuse

One callback URL is associated with one address family and one address_in. Reusing the same callback URL is allowed only when the requested network uses the same compatible address format.

Representative callback reuse outcomes
First requestLater requestOutcomeReason
BSCEthereumReuseBoth use the EVM address family.
EVMBitcoinConflictThe address families differ.
BitcoinLitecoinConflictEach UTXO coin has its own address and signing network.
SolanaEVMConflictThe address families differ.

Use a unique callback URL per order and address family. A cross-family request returns HTTP 409 and does not create or modify a wallet.

HTTP 409
{
  "status": "error",
  "code": 1202,
  "error": "CALLBACK_ADDRESS_FAMILY_CONFLICT",
  "message": "The callback URL is already associated with another address family. Use a new callback URL for this network."
}

Repeated create requests are immutable

If a compatible wallet already exists for the callback URL, CryptPays returns its stored configuration. A later create request does not update its address_out, confirmations, priority, callback transport, or minimum snapshot.

Compatible networks

Automatic EVM Multi-Network and Token Handling

An EVM deposit address belongs to the EVM address family rather than exclusively to the ticker used when it was created. No extra merchant switch is required.

Example

Create bep20_usdt and receive 0xABC…. For enabled supported assets, that same address can independently receive BSC USDT, BSC USDC, ETH, ERC-20 USDT, Polygon assets, and other compatible EVM deposits.

Deposit APayment AForward ACallback A
Deposit BPayment BForward BCallback B

Deposits are never combined. Each incoming blockchain transaction has its own accounting, forwarding operation, stable callback UUID, and callback lifecycle.

Processing threshold

Minimum Transactions

The minimum is the smallest independent deposit CryptPays currently considers safe and economic for automatic processing on a specific network and asset.

  • Minimums are asset- and network-specific decimal strings.
  • They can change with network conditions and operator safety settings.
  • Read the current value from /api/cryptocurrencies or /api/{ticker}/info.
  • The published value uses default network-priority economics; choosing slow or fast does not rewrite it.

Current value versus create snapshot

/cryptocurrencies and /info

Return the current authoritative minimum for the asset.

/create

Returns minimum_transaction_coin, the snapshot stored when that address configuration was created. A compatible repeat returns the original snapshot.

When presenting current payment instructions, consult public metadata rather than assuming an older wallet snapshot still equals today’s network minimum.

Finality

Confirmations and Finality

Numeric-confirmation networks have an operator default and an operator-configured maximum merchant override.

OmittedThe network default applies.
Below defaultThe network default still applies.
Default through maximumThe requested value applies.
Above maximumThe new create request is rejected.

The actual processing threshold is never below the current network default. A compatible repeat create request does not update the stored confirmation preference, and changing the configured maximum does not reduce an existing higher requirement.

Forwarding speed

Transaction Priority

Priority defaults to default. Explicit slow or fast values are accepted only where they change the actual forwarding transaction.

Merchant-selectable priority by family
Network or familySupported valuesBehavior
Bitcoin, Litecoin, Bitcoin Cash, Dogecoinslow, default, fastSelects the corresponding network fee tier.
Solana and SPLslow, default, fastSelects the configured transaction priority fee.
ZcashdefaultPreserves ZIP-317 fee behavior.
EVMdefaultSlow and fast are rejected.
TRONdefaultSlow and fast are rejected.

Actual forwarding uses the stored supported priority. The public transaction minimum remains based on default or medium economics and is not personalized by merchant priority.

Callback amounts

Fees and Accounting

The confirmed callback separates the contracted CryptPays percentage from the total amount deducted before merchant forwarding.

fee

Contracted percentage

The actual CryptPays percentage charged to this transaction.

fee_coin

Total deduction

The difference between the deposit and merchant-forwarded amounts.

value_coin=value_forwarded_coin+fee_coin

fee_coin can include the CryptPays commission, recovered miner or gas costs, and applicable Solana network, rent, or token-account recovery. It is not the percentage commission alone.

Illustrative accounting example

Deposit
100 USDT
CryptPays percentage
1.00%
Recovered network cost
0.20 USDT
Merchant receives
98.80 USDT
Callback fields
{
  "value_coin": "100.00",
  "value_forwarded_coin": "98.80",
  "fee": "1.00",
  "fee_coin": "1.20"
}

These numbers are illustrative and do not state a current CryptPays fee or network cost.

Keyless domain and volume tiers

The callback hostname participates in merchant fee-tier identity. CryptPays selects an active domain flat fee when present, otherwise the domain’s volume tier, then the default fallback. The fee_percent shown by /info is the generic public default; the confirmed callback’s fee is the actual percentage charged and may differ.

USDT price and conversion

Callback price is a USDT quote captured for the confirmed payment. When convert=1, conversion fields can also be included in USDT. See the callback payload reference for their wire format.

Next steps

Apply these concepts

PaymentsCreate options, payment instructions, and logs. CallbacksLifecycle, payloads, acknowledgement, retries, and signatures. API ReferenceExact endpoint and error contracts. Integration GuidesLanguage and blockchain-family examples.