Cryptocurrency Payment API for Developers

Integration flow

From canonical ticker to verified fulfillment

The website introduces the contract; the documentation remains the complete endpoint and network reference.

01DiscoverGET /cryptocurrencies
02CreatePOST /{ticker}/create
03Presentaddress_in
04Customer paysOne blockchain deposit
05DetectMatch supported-chain activity
06FinalizeConfirmation or finality
07ReceiveSigned callback
08VerifySignature + timestamp
09Fulfill onceUUID idempotency
10AcknowledgeHTTP 200

Public integration, explicit trust boundary.

Asset discovery and payment-address creation do not require merchant API credentials. You provide a validated callback destination and payout address_out; CryptPays returns an address_in. Verify the signed callback before trusting payment data or fulfilling an order. Administrative APIs are separate.

1 · Discover

Start with live asset metadata

GET /api/cryptocurrencies returns an object keyed by canonical ticker. Use the returned ticker in create, info, and logs routes rather than inferring it from a symbol or maintaining a static asset list.

minimum is an exact decimal string when current informational metadata is available. It can be null temporarily without making the enabled asset unsupported.

Read the catalog contract

curl 'https://api.cryptpays.com/api/cryptocurrencies'

{
  "bep20_usdt": {
    "ticker": "bep20_usdt",
    "asset_name": "Tether",
    "symbol": "USDT",
    "network_name": "BNB Smart Chain",
    "minimum": null,
    "confirmations_required": 15
  }
}

2 · Create

Create a payment address for your callback identity

callback_url and address_out are required. The ticker belongs in the route—not the request body—and the endpoint does not register or require an expected invoice amount.

The optional post=1 and json=1 fields select recommended JSON POST callback delivery. Calling /create with POST alone does not change the callback method; GET delivery remains the compatibility default.

Each observed blockchain deposit is an independent payment. Correlate it to your order through stable merchant callback metadata, then validate your business amount only after authenticating the callback.

Review every create parameter

curl -X POST \
  'https://api.cryptpays.com/api/bep20_usdt/create' \
  -H 'Content-Type: application/json' \
  -d '{
    "callback_url": "https://merchant.example/payments/callback?order_id=ORDER-123",
    "address_out": "0x1111111111111111111111111111111111111111",
    "post": 1,
    "json": 1
  }'

{
  "address_in": "0x2222222222222222222222222222222222222222",
  "address_out": "0x1111111111111111111111111111111111111111",
  "callback_url": "https://merchant.example/payments/callback?order_id=ORDER-123",
  "priority": "default",
  "minimum_transaction_coin": "1.250000000000000000",
  "status": "success"
}

Minimums are not invoice amounts. minimum_transaction_coin is the address configuration's creation-time snapshot. Current public metadata can change with network conditions or operator safety floors, while CryptPays evaluates each observed payment against its applicable processing and forwarding economics.

Minimum transaction model

3 · Observe the lifecycle

One deposit, one chain-aware payment lifecycle

CryptPays detects supported-chain activity, applies the appropriate confirmation or finality model, forwards a qualifying payment, and produces its signed merchant event.

01
Customer sends
Present address_in together with the intended asset, network, and current informational minimum.
02
CryptPays detects
Supported-chain activity is matched to the generated deposit address. Every blockchain deposit remains independent.
03
Confirmation or finality
Numeric networks use the effective confirmation depth. Solana exposes pending/not-final as 0 and confirmed/final as 1.
04
Forward and notify
A qualifying payment advances through forwarding and a signed confirmed callback with its immutable accounting snapshot.

View current confirmation and finality metadata

4 · Verify the callback

Authenticate the event before advancing your order

CryptPays callbacks retain the compatibility headers X-CryptPay-Signature and X-CryptPay-Timestamp. RSA-SHA256 verification covers the documented canonical request, including the exact raw body.

Preserve bytesCapture the exact request body before JSON or form parsing.
Check freshnessValidate the numeric timestamp against the documented tolerance.
Verify signatureUse the current public key and documented canonical input.
Validate fieldsConfirm your merchant reference, canonical coin, and lifecycle stage.
Commit onceProcess the stable callback UUID transactionally and idempotently.
Fulfill confirmedFulfill only result=sent with pending=0.
AcknowledgeReturn exactly HTTP 200 after safe processing; the response body is ignored.

Non-200 delivery responses may be retried under the bounded callback policy. A retry can repeat the same event, so idempotency is required.

Implement signature verification

X-CryptPay-Timestamp: <unix-seconds>
X-CryptPay-Signature: <base64-signature>

{
  "uuid": "9ab63121-41f8-4c56-9c28-c78e9b44b487",
  "coin": "bep20_usdt",
  "value_coin": "100.000000000000000000",
  "value_forwarded_coin": "98.300000000000000000",
  "fee": "1.50",
  "fee_coin": "1.700000000000000000",
  "result": "sent",
  "pending": 0
}

The values above illustrate callback field types and relationships; they are not a statement of current standard pricing.

Integration principles

Build against current metadata and explicit state

The contract accommodates runtime availability, independent deposits, repeated delivery, and exact decimal accounting.

Do not invent fallback metadata

If a catalog minimum is null or an API call fails, retain the supported asset identity but do not substitute zero, a guessed ticker, or a stale hardcoded minimum.

Expect repeat delivery

When pending notifications are enabled, one UUID can advance from pending to confirmed. The same confirmed delivery can be retried and must never fulfill twice.

Keep decimal values as strings

Money fields are decimal strings. Reconcile value_coin = value_forwarded_coin + fee_coin without binary floating-point arithmetic.

Reconcile by callback identity

GET /api/{ticker}/logs?callback=... returns payment and delivery history for the exact stored callback URL. It is a reconciliation endpoint, not a fulfillment signal.

Handle explicit failures

Treat non-2xx API responses as failures and follow documented error codes. Do not repeatedly retry invalid assets or addresses as though they were transient.

Keep network identity visible

The same symbol can exist on multiple networks. Present the asset, network, and canonical ticker together when instructing a customer.

Payment accounting

Reconcile the deposit and amount forwarded

The confirmed callback separates the incoming amount, forwarded amount, actual percentage, and total deduction. Network-related deductions are included in fee_coin, not hidden inside the percentage.

Understand standard pricing and network costs

value_coin: Incoming amount for this independent payment.
value_forwarded_coin: Amount forwarded to the merchant payout address.
fee: Actual percentage applied to this payment.
fee_coin: Total deduction in the payment asset, including applicable network-related recovery.

Public API quick reference

The endpoints most integrations need

These routes are public Merchant API surfaces. Standard pricing is optional integration metadata; it is not required to create or process a payment.

GET /cryptocurrencies

Discover assets

Current enabled mainnet assets, canonical tickers, public minimum metadata, and confirmation/finality requirements.

Catalog schema

GET /pricing

Read standard pricing

The current validated global/default rolling-volume schedule. Merchant-specific commercial terms are not exposed.

Pricing overview

GET /{ticker}/info

Inspect one asset

Current metadata for an enabled ticker, including informational minimum and confirmation/finality requirement.

Info schema

GET|POST /{ticker}/create

Create payment configuration

Store the callback and payout destination and receive the customer deposit address.

Create contract

GET /{ticker}/logs

Reconcile payment history

Query the exact stored callback URL identity for payment lifecycle and recent delivery-attempt records.

Logs contract

GET /pubkey

Verify callbacks

Retrieve the current PEM public key used for RSA-SHA256 callback signature verification.

Public-key contract

Integration FAQ

Decisions to make before production

Keep order state in your application, treat callback verification as mandatory, and use the maintained documentation for complete network-specific behavior.

Does payment creation require an API key?

No merchant API credential is required for public asset discovery or normal payment-address creation. That does not make callback data trusted: verify its signature and timestamp before fulfillment. Administrative APIs are separate.

Does /create register the order amount?

No. CryptPays creates the payment address configuration; each blockchain deposit is processed independently. Your application owns the expected order amount and validates it against an authenticated payment event.

What if the catalog minimum is null?

The asset can remain supported while current informational minimum metadata is temporarily unavailable. Do not replace it with zero or a guessed value.

Can a callback be delivered more than once?

Yes. Non-200 responses may be retried. Persist the UUID and make confirmed fulfillment idempotent before returning HTTP 200.

Where can I inspect a payment lifecycle?

Use GET /api/{ticker}/logs with the exact callback URL stored at creation. Logs are useful for reconciliation; authenticated confirmed callbacks remain the fulfillment event.

Build with CryptPays

Move from overview to implementation

The documentation contains complete schemas, validation rules, callback verification examples, error contracts, and network-specific behavior.

Read Documentation Review Security Discuss an integration