Integration Guides

1. 1DiscoverCatalog and info
2. 2CreatePayment address
3. 3PresentNetwork + address
4. 4VerifySigned callback
5. 5FulfillIdempotently
6. 6HTTP 200Acknowledge

Discover and create

This runnable PHP example requests current metadata, then explicitly selects JSON POST callbacks. Omitting post keeps the API’s GET callback default.

<?php

function cryptPayJson(string $method, string $url, ?array $body = null): array
{
    $curl = curl_init($url);
    $options = [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 15,
        CURLOPT_HTTPHEADER => ['Accept: application/json'],
    ];

    if ($method === 'POST') {
        $options[CURLOPT_POST] = true;
        $options[CURLOPT_HTTPHEADER][] = 'Content-Type: application/json';
        $options[CURLOPT_POSTFIELDS] = json_encode($body, JSON_THROW_ON_ERROR);
    }

    curl_setopt_array($curl, $options);
    $responseBody = curl_exec($curl);
    $status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);

    if (!is_string($responseBody) || $status !== 200) {
        throw new RuntimeException('CryptPays request failed with HTTP ' . $status);
    }

    return json_decode($responseBody, true, 512, JSON_THROW_ON_ERROR);
}

$apiBase = 'https://api.cryptpays.com/api';
$ticker = 'bep20_usdt';
$callbackUrl = 'https://merchant.example/payments/callback?order_id=123';
$addressOut = '0x1111111111111111111111111111111111111111';

$info = cryptPayJson('GET', "$apiBase/$ticker/info");
$payment = cryptPayJson('POST', "$apiBase/$ticker/create", [
    'callback_url' => $callbackUrl,
    'address_out' => $addressOut,
    'post' => 1,
    'json' => 1,
]);

// Persist the order reference, ticker, exact callback URL, address_in,
// address_out, and minimum_transaction_coin snapshot as decimal strings.
printf("Send %s to %s on %s\n", $ticker, $payment['address_in'], $info['ticker']);

Verify, transition, fulfill

Use the copy-ready PHP verifier to read the raw request, enforce the 300-second window, and verify RSA-SHA256 before parsing. Then apply this production flow transactionally:

Discover and create

const apiBase = 'https://api.cryptpays.com/api';
const ticker = 'bep20_usdt';
const callbackUrl = 'https://merchant.example/payments/callback?order_id=123';

const infoResponse = await fetch(`${apiBase}/${ticker}/info`);
if (!infoResponse.ok) throw new Error(`Info failed: HTTP ${infoResponse.status}`);
const info = await infoResponse.json();

const createResponse = await fetch(`${apiBase}/${ticker}/create`, {
  method: 'POST',
  headers: { 'content-type': 'application/json', accept: 'application/json' },
  body: JSON.stringify({
    callback_url: callbackUrl,
    address_out: '0x1111111111111111111111111111111111111111',
    post: 1,
    json: 1,
  }),
});

if (!createResponse.ok) throw new Error(`Create failed: HTTP ${createResponse.status}`);
const payment = await createResponse.json();

// Persist callbackUrl, info.ticker, payment.address_in, payment.address_out,
// and payment.minimum_transaction_coin using decimal-safe string handling.
console.log({ ticker: info.ticker, addressIn: payment.address_in });

Preserve callback bytes

The validated Express verifier provides the complete canonicalization and node:crypto code. Its middleware order is essential:

// Register this route before express.json() or express.urlencoded().
app.all('/payments/callback', express.raw({ type: () => true }), async (req, res) => {
  // Verify timestamp + signature over method, host, req.originalUrl,
  // and the exact req.body Buffer. Parse only after verification passes.
  const payload = await verifyAndParseCryptPaysCallback(req);

  if (payload.result === 'sent' && Number(payload.pending) === 0) {
    // In one durable DB transaction: validate order + coin, allow pending → sent,
    // and fulfill this confirmed UUID only if fulfilled_at is still empty.
    await processConfirmedPaymentIdempotently(payload);
  }

  return res.sendStatus(200);
});

Integration skeleton: use the complete verifier linked above for verifyAndParseCryptPaysCallback and implement the durable merchant transaction in your own storage layer. Do not replace it with an in-memory Set.

Reuse and priority

• The same callback URL across compatible EVM assets returns the existing EVM address and configuration.
• Repeated /create does not update address_out, confirmations, priority, transport, pending, or conversion settings.
• Use a new callback URL when you need a separate configuration.
• EVM accepts priority=default only; explicit slow or fast returns 1103 UNSUPPORTED_PRIORITY.

Confirmations and priority

confirmations is the incoming customer-deposit count, never the outbound-forward count. You may request a higher threshold within current operator limits; a lower request cannot reduce the network default.

The public minimum remains based on default/medium economics even when a wallet selects slow or fast. Consult live metadata rather than hardcoding a threshold.

Independent principal and costs

Every incoming SOL or SPL deposit is one independent payment with its own UUID, accounting, forward, and callback. Earlier wallet or token balances are not added to a later deposit’s principal, and quick successive deposits remain separate.

Applicable Solana network and rent-related recovery can contribute to fee_coin; fee remains the contracted CryptPays percentage. Reconcile using value_coin = value_forwarded_coin + fee_coin.

• TRON follows the numeric-chain confirmation rules: the operator default is the floor, and higher merchant requests must remain within the configured maximum.
• TRON currently accepts priority=default only. Explicit slow or fast is rejected.
• If a TRON asset is disabled or unavailable, it does not appear in /api/cryptocurrencies.

No resource-management or delegation setting is required from merchants.

• Use /api/cryptocurrencies for current supported assets.
• Use /info for current minimum and default metadata.
• Use a stable unique callback URL per order and address family.
• Display both network and asset clearly to the customer.
• Do not assume /create registers an expected amount.
• Set post=1, json=1 explicitly when JSON POST is desired.
• Keep pending off unless an early informational event is useful.
• Verify timestamp and signature before trusting callback fields.
• Preserve exact raw callback bytes for verification.
• Fulfill only result=sent, pending=0.
• Use persistent lifecycle-aware idempotency.
• Return exactly HTTP 200 after successful handling.
• Treat monetary values as decimal strings or base-unit-safe values.
• Use txid_in plus vout for UTXO identity.
• Use runtime minimums instead of hardcoded values.
• Test callbacks through the real proxy, firewall, and WAF path.